idnits 2.17.1 draft-ietf-isms-dtls-tm-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. 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 369 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 (October 22, 2009) is 5300 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) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 2 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 October 22, 2009 5 Expires: April 25, 2010 7 Transport Layer Security Transport Model for SNMP 8 draft-ietf-isms-dtls-tm-01.txt 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may contain material 14 from IETF Documents or IETF Contributions published or made publicly 15 available before November 10, 2008. The person(s) controlling the 16 copyright in some of this material may not have granted the IETF 17 Trust the right to allow modifications of such material outside the 18 IETF Standards Process. Without obtaining an adequate license from 19 the person(s) controlling the copyright in such materials, this 20 document may not be modified outside the IETF Standards Process, and 21 derivative works of it may not be created outside the IETF Standards 22 Process, except to format it for publication as an RFC or to 23 translate it into languages other than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on April 25, 2010. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This document describes a Transport Model for the Simple Network 57 Management Protocol (SNMP), that uses either the Transport Layer 58 Security protocol or the Datagram Transport Layer Security (DTLS) 59 protocol. The TLS and DTLS protocols provide authentication and 60 privacy services for SNMP applications. This document describes how 61 the TLS Transport Model (TLSTM) implements the needed features of a 62 SNMP Transport Subsystem to make this protection possible in an 63 interoperable way. 65 This transport model is designed to meet the security and operational 66 needs of network administrators. The TLS mode can make use of TCP's 67 improved support for larger packet sizes and the DTLS mode provides 68 potentially superior operation in environments where a connectionless 69 (e.g. UDP or SCTP) transport is preferred. Both TLS and DTLS 70 integrate well into existing public keying infrastructures. 72 This document also defines a portion of the Management Information 73 Base (MIB) for use with network management protocols. In particular 74 it defines objects for managing the TLS Transport Model for SNMP. 76 Table of Contents 78 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 79 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 7 80 2. The Transport Layer Security Protocol . . . . . . . . . . . . 8 81 2.1. SNMP requirements of (D)TLS . . . . . . . . . . . . . . . 8 82 3. How the TLSTM fits into the Transport Subsystem . . . . . . . 8 83 3.1. Security Capabilities of this Model . . . . . . . . . . . 10 84 3.1.1. Threats . . . . . . . . . . . . . . . . . . . . . . . 10 85 3.1.2. Message Protection . . . . . . . . . . . . . . . . . . 12 86 3.1.3. (D)TLS Sessions . . . . . . . . . . . . . . . . . . . 13 87 3.2. Security Parameter Passing . . . . . . . . . . . . . . . . 13 88 3.3. Notifications and Proxy . . . . . . . . . . . . . . . . . 14 89 4. Elements of the Model . . . . . . . . . . . . . . . . . . . . 14 90 4.1. X.509 Certificates . . . . . . . . . . . . . . . . . . . . 15 91 4.1.1. Provisioning for the Certificate . . . . . . . . . . . 15 92 4.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 16 93 4.3. SNMP Services . . . . . . . . . . . . . . . . . . . . . . 16 94 4.3.1. SNMP Services for an Outgoing Message . . . . . . . . 16 95 4.3.2. SNMP Services for an Incoming Message . . . . . . . . 17 96 4.4. (D)TLS Services . . . . . . . . . . . . . . . . . . . . . 18 97 4.4.1. Services for Establishing a Session . . . . . . . . . 18 98 4.4.2. (D)TLS Services for an Incoming Message . . . . . . . 19 99 4.4.3. (D)TLS Services for an Outgoing Message . . . . . . . 20 100 4.5. Cached Information and References . . . . . . . . . . . . 21 101 4.5.1. TLS Transport Model Cached Information . . . . . . . . 21 102 5. Elements of Procedure . . . . . . . . . . . . . . . . . . . . 21 103 5.1. Procedures for an Incoming Message . . . . . . . . . . . . 22 104 5.1.1. DTLS Processing for Incoming Messages . . . . . . . . 22 105 5.1.2. Transport Processing for Incoming Messages . . . . . . 23 106 5.2. Procedures for an Outgoing Message . . . . . . . . . . . . 25 107 5.3. Establishing a Session . . . . . . . . . . . . . . . . . . 26 108 5.4. Closing a Session . . . . . . . . . . . . . . . . . . . . 28 109 6. MIB Module Overview . . . . . . . . . . . . . . . . . . . . . 29 110 6.1. Structure of the MIB Module . . . . . . . . . . . . . . . 29 111 6.2. Textual Conventions . . . . . . . . . . . . . . . . . . . 29 112 6.3. Statistical Counters . . . . . . . . . . . . . . . . . . . 29 113 6.4. Configuration Tables . . . . . . . . . . . . . . . . . . . 29 114 6.4.1. Notifications . . . . . . . . . . . . . . . . . . . . 30 115 6.5. Relationship to Other MIB Modules . . . . . . . . . . . . 30 116 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 30 117 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 30 118 8. Operational Considerations . . . . . . . . . . . . . . . . . . 53 119 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 53 120 8.2. Notification Receiver Credential Selection . . . . . . . . 54 121 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 54 122 9. Security Considerations . . . . . . . . . . . . . . . . . . . 55 123 9.1. Certificates, Authentication, and Authorization . . . . . 55 124 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 56 125 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 56 126 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 127 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59 128 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 129 12.1. Normative References . . . . . . . . . . . . . . . . . . . 59 130 12.2. Informative References . . . . . . . . . . . . . . . . . . 61 131 Appendix A. (D)TLS Overview . . . . . . . . . . . . . . . . . . . 62 132 A.1. The (D)TLS Record Protocol . . . . . . . . . . . . . . . . 62 133 A.2. The (D)TLS Handshake Protocol . . . . . . . . . . . . . . 62 134 Appendix B. PKIX Certificate Infrastructure . . . . . . . . . . . 63 135 Appendix C. Target and Notificaton Configuration Example . . . . 64 136 C.1. Configuring the Notification Generator . . . . . . . . . . 65 137 C.2. Configuring the Command Responder . . . . . . . . . . . . 65 138 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 66 140 1. Introduction 142 It is important to understand the modular SNMPv3 architecture as 143 defined by [RFC3411] and enhanced by the Transport Subsystem 144 [RFC5590]. It is also important to understand the terminology of the 145 SNMPv3 architecture in order to understand where the Transport Model 146 described in this document fits into the architecture and how it 147 interacts with the other architecture subsystems. For a detailed 148 overview of the documents that describe the current Internet-Standard 149 Management Framework, please refer to Section 7 of [RFC3410]. 151 This document describes a Transport Model that makes use of the 152 Transport Layer Security (TLS) [RFC5246] and the Datagram Transport 153 Layer Security (DTLS) Protocol [RFC4347], within a transport 154 subsystem [RFC5590]. DTLS is the datagram variant of the Transport 155 Layer Security (TLS) protocol [RFC5246]. The Transport Model in this 156 document is referred to as the Transport Layer Security Transport 157 Model (TLSTM). TLS and DTLS take advantage of the X.509 public 158 keying infrastructure [RFC5280]. This transport model is designed to 159 meet the security and operational needs of network administrators, 160 operate in both environments where a connectionless (e.g. UDP or 161 SCTP) transport is preferred and in environments where large 162 quantities of data need to be sent (e.g. over a TCP based stream). 163 Both TLS and DTLS integrate well into existing public keying 164 infrastructures. 166 This document also defines a portion of the Management Information 167 Base (MIB) for use with network management protocols. In particular 168 it defines objects for managing the TLS Transport Model for SNMP. 170 For a detailed overview of the documents that describe the current 171 Internet-Standard Management Framework, please refer to section 7 of 172 RFC [RFC3410]. 174 Managed objects are accessed via a virtual information store, termed 175 the Management Information Base or MIB. MIB objects are generally 176 accessed through the Simple Network Management Protocol (SNMP). 177 Objects in the MIB are defined using the mechanisms defined in the 178 Structure of Management Information (SMI). This memo specifies a MIB 179 module that is compliant to the SMIv2, which is described in STD 58: 180 [RFC2578], [RFC2579] and [RFC2580]. 182 The diagram shown below gives a conceptual overview of two SNMP 183 entities communicating using the TLS Transport Model. One entity 184 contains a Command Responder and Notification Originator application, 185 and the other a Command Generator and Notification Responder 186 application. It should be understood that this particular mix of 187 application types is an example only and other combinations are 188 equally as legitimate. 190 +----------------------------------------------------------------+ 191 | Network | 192 +----------------------------------------------------------------+ 193 ^ | ^ | 194 |Notifications |Commands |Commands |Notifications 195 +---|---------------------|--------+ +--|---------------|-------------+ 196 | | V | | | V | 197 | +------------+ +------------+ | | +-----------+ +----------+ | 198 | | (D)TLS | | (D)TLS | | | | (D)TLS | | (D)TLS | | 199 | | Service | | Service | | | | Service | | Service | | 200 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 201 | +------------+ +------------+ | | +-----------+ +----------+ | 202 | ^ ^ | | ^ ^ | 203 | | | | | | | | 204 | +--+----------+ | | +-+--------------+ | 205 | +-----|---------+----+ | | +---|--------+----+ | 206 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 207 | | +------+ +----+ | | | | | +------+ +----+ | | | 208 | | | DTLS | <---------->| Cache | | | | | DTLS | <---->| Cache | | 209 | | | TM | | | | | | | | TM | | | | | 210 | | +------+ | +-------+ | | | +------+ | +--------+ | 211 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 212 | +--------------------+ | | | +-----------------+ | | 213 | ^ +----+ | | ^ | | 214 | | | | | | | | 215 | v | | | V | | 216 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 217 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 218 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 219 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 220 | | | | | | | | | | | | | | | | | | 221 | | | | | |+---+| | | | | | | | |+---+| | | 222 | | | | +-----+ | || || | | | | | |+----+| || || | | 223 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 224 | | | | +-----+ | || || | | | | |+----+| || || | 225 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 226 | ^ | | | | | | ^ | | | | | 227 | | +----------+ +-----+ | | | +------+ +-----+ | 228 | +-+------------+ | | +-+------------+ | 229 | ^ ^ | | ^ ^ | 230 | | | | | | | | 231 | v v | | V V | 232 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 233 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 234 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RESPONDER | | 235 | | application | | applications | | | |application| | application | | 236 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 237 | SNMP entity | | SNMP entity | 238 +----------------------------------+ +--------------------------------+ 240 1.1. Conventions 242 For consistency with SNMP-related specifications, this document 243 favors terminology as defined in STD62 rather than favoring 244 terminology that is consistent with non-SNMP specifications. This is 245 consistent with the IESG decision to not require the SNMPv3 246 terminology be modified to match the usage of other non-SNMP 247 specifications when SNMPv3 was advanced to Full Standard. 249 Authentication in this document typically refers to the English 250 meaning of "serving to prove the authenticity of" the message, not 251 data source authentication or peer identity authentication. 253 Large portions of this document simultaneously refer to both TLS and 254 DTLS when discussing TLSTM components that function equally with 255 either protocol. "(D)TLS" is used in these places to indicate that 256 the statement applies to either or both protocols as appropriate. 257 When a distinction between the protocols is needed they are referred 258 to independently through the use of "TLS" or "DTLS". The Transport 259 Model, however, is named "TLS Transport Model" and refers not to the 260 TLS or DTLS protocol but to the standard defined in this document, 261 which includes support for both TLS and DTLS. 263 The terms "manager" and "agent" are not used in this document, 264 because in the RFC 3411 architecture [RFC3411], all SNMP entities 265 have the capability of acting in either manager or agent or in both 266 roles depending on the SNMP application types supported in the 267 implementation. Where distinction is required, the application names 268 of Command Generator, Command Responder, Notification Originator, 269 Notification Receiver, and Proxy Forwarder are used. See "SNMP 270 Applications" [RFC3413] for further information. 272 Throughout this document, the terms "client" and "server" are used to 273 refer to the two ends of the (D)TLS transport connection. The client 274 actively opens the (D)TLS connection, and the server passively 275 listens for the incoming (D)TLS connection. Either SNMP entity may 276 act as client or as server. 278 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 279 implement Security Model in STD 62. While (D)TLS and USM frequently 280 refer to a user, the terminology preferred in RFC3411 and in this 281 memo is "principal". A principal is the "who" on whose behalf 282 services are provided or processing takes place. A principal can be, 283 among other things, an individual acting in a particular role; a set 284 of individuals, with each acting in a particular role; an application 285 or a set of applications, or a combination of these within an 286 administrative domain. 288 Throughout this document, the term "session" is used to refer to a 289 secure association between two TLS Transport Models that permits the 290 transmission of one or more SNMP messages within the lifetime of the 291 session. 293 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 294 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 295 document are to be interpreted as described in [RFC2119]. 297 2. The Transport Layer Security Protocol 299 (D)TLS provides authentication, data message integrity, and privacy 300 at the transport layer. (See [RFC4347]) 302 The primary goals of the TLS Transport Model are to provide privacy, 303 source authentication and data integrity between two communicating 304 SNMP entities. The TLS and DTLS protocols provide a secure transport 305 upon which the TLSTM is based. An overview of (D)TLS can be found in 306 section Appendix A. Please refer to [RFC5246] and [RFC4347] for 307 complete descriptions of the protocols. 309 2.1. SNMP requirements of (D)TLS 311 To properly support the SNMP over TLS Transport Model, the (D)TLS 312 implementation requires the following: 314 o The TLS Transport Model SHOULD always use authentication of both 315 the server and the client. 317 o At a minimum the TLS Transport Model MUST support authentication 318 of the Command Generator, Notification Originator and Proxy 319 Forwarder principals to guarantee the authenticity of the 320 securityName. 322 o The TLS Transport Model SHOULD support the message encryption to 323 protect sensitive data from eavesdropping attacks. 325 3. How the TLSTM fits into the Transport Subsystem 327 A transport model is a component of the Transport Subsystem. The TLS 328 Transport Model thus fits between the underlying (D)TLS transport 329 layer and the message dispatcher [RFC3411] component of the SNMP 330 engine and the Transport Subsystem. 332 The TLS Transport Model will establish a session between itself and 333 the TLS Transport Model of another SNMP engine. The sending 334 transport model passes unprotected messages from the dispatcher to 335 (D)TLS to be protected, and the receiving transport model accepts 336 decrypted and authenticated/integrity-checked incoming messages from 337 (D)TLS and passes them to the dispatcher. 339 After a TLS Transport Model session is established, SNMP messages can 340 conceptually be sent through the session from one SNMP message 341 dispatcher to another SNMP message dispatcher. If multiple SNMP 342 messages are needed to be passed between two SNMP applications they 343 SHOULD be passed through the same session. A TLSTM implementation 344 engine MAY choose to close a (D)TLS session to conserve resources. 346 The TLS Transport Model of an SNMP engine will perform the 347 translation between (D)TLS-specific security parameters and SNMP- 348 specific, model-independent parameters. 350 The diagram below depicts where the TLS Transport Model fits into the 351 architecture described in RFC3411 and the Transport Subsystem: 353 +------------------------------+ 354 | Network | 355 +------------------------------+ 356 ^ ^ ^ 357 | | | 358 v v v 359 +-------------------------------------------------------------------+ 360 | +--------------------------------------------------+ | 361 | | Transport Subsystem | +--------+ | 362 | | +-----+ +-----+ +-------+ +-------+ | | | | 363 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 364 | | | | | TM | | TM | | | | | | | 365 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 366 | +--------------------------------------------------+ ^ | 367 | ^ | | 368 | | | | 369 | Dispatcher v | | 370 | +--------------+ +---------------------+ +----------------+ | | 371 | | Transport | | Message Processing | | Security | | | 372 | | Dispatch | | Subsystem | | Subsystem | | | 373 | | | | +------------+ | | +------------+ | | | 374 | | | | +->| v1MP |<--->| | USM | | | | 375 | | | | | +------------+ | | +------------+ | | | 376 | | | | | +------------+ | | +------------+ | | | 377 | | | | +->| v2cMP |<--->| | Transport | | | | 378 | | Message | | | +------------+ | | | Security |<--+ | 379 | | Dispatch <---->| +------------+ | | | Model | | | 380 | | | | +->| v3MP |<--->| +------------+ | | 381 | | | | | +------------+ | | +------------+ | | 382 | | PDU Dispatch | | | +------------+ | | | Other | | | 383 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 384 | ^ | +------------+ | | +------------+ | | 385 | | +---------------------+ +----------------+ | 386 | v | 387 | +-------+-------------------------+---------------+ | 388 | ^ ^ ^ | 389 | | | | | 390 | v v v | 391 | +-------------+ +---------+ +--------------+ +-------------+ | 392 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 393 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 394 | | application | | | | applications | | application | | 395 | +-------------+ +---------+ +--------------+ +-------------+ | 396 | ^ ^ | 397 | | | | 398 | v v | 399 | +----------------------------------------------+ | 400 | | MIB instrumentation | SNMP entity | 401 +-------------------------------------------------------------------+ 403 3.1. Security Capabilities of this Model 405 3.1.1. Threats 407 The TLS Transport Model provides protection against the threats 408 identified by the RFC 3411 architecture [RFC3411]: 410 1. Modification of Information - The modification threat is the 411 danger that some unauthorized entity may alter in-transit SNMP 412 messages generated on behalf of an authorized principal in such a 413 way as to effect unauthorized management operations, including 414 falsifying the value of an object. 416 (D)TLS provides verification that the content of each received 417 message has not been modified during its transmission through the 418 network, data has not been altered or destroyed in an 419 unauthorized manner, and data sequences have not been altered to 420 an extent greater than can occur non-maliciously. 422 2. Masquerade - The masquerade threat is the danger that management 423 operations unauthorized for a given principal may be attempted by 424 assuming the identity of another principal that has the 425 appropriate authorizations. 427 The TLSTM provides for authentication of the Command Generator, 428 Command Responder, Notification Generator, Notification Responder 429 and Proxy Forwarder through the use of X.509 certificates. 431 The masquerade threat can be mitigated against by using an 432 appropriate Access Control Model (ACM) such as the View-based 433 Access Control Module (VACM) [RFC3415]. 435 3. Message stream modification - The re-ordering, delay or replay of 436 messages can and does occur through the natural operation of many 437 connectionless transport services. The message stream 438 modification threat is the danger that messages may be 439 maliciously re-ordered, delayed or replayed to an extent which is 440 greater than can occur through the natural operation of 441 connectionless transport services, in order to effect 442 unauthorized management operations. 444 (D)TLS provides replay protection with a MAC that includes a 445 sequence number. Since UDP provides no sequencing ability DTLS 446 uses a sliding window protocol with the sequence number for 447 replay protection (see [RFC4347]). 449 4. Disclosure - The disclosure threat is the danger of eavesdropping 450 on the exchanges between SNMP engines. 452 Symmetric cryptography (e.g., [AES], [DES] etc.) can be used by 453 (D)TLS for data privacy. The keys for this symmetric encryption 454 are generated uniquely for each session and are based on a secret 455 negotiated by another protocol (such as the (D)TLS Handshake 456 Protocol). 458 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 459 that denial of service (DoS) attacks need not be addressed by an 460 SNMP security protocol. However, datagram-based security 461 protocols like DTLS are susceptible to a variety of denial of 462 service attacks because it is more vulnerable to spoofed 463 messages. 465 In order to counter these attacks, DTLS borrows the stateless 466 cookie technique used by Photuris [RFC2522] and IKEv2 [RFC4306] 467 and is described fully in section 4.2.1 of [RFC4347]. This 468 mechanism, though, does not provide any defense against denial of 469 service attacks mounted from valid IP addresses. DTLS Transport 470 Model server implementations MUST support DTLS cookies. 472 Implementations are not required to perform the stateless cookie 473 exchange for every DTLS handshakes but in environments where 474 amplification could be an issue or has been detected it is 475 RECOMMENDED that the cookie exchange is utilized. 477 See Section 9 for more detail on the security considerations 478 associated with the DTLSTM and these security threats. 480 3.1.2. Message Protection 482 The RFC 3411 architecture recognizes three levels of security: 484 o without authentication and without privacy (noAuthNoPriv) 486 o with authentication but without privacy (authNoPriv) 488 o with authentication and with privacy (authPriv) 490 The TLS Transport Model determines from (D)TLS the identity of the 491 authenticated principal, and the type and address associated with an 492 incoming message. The TLS Transport Model provides this information 493 to (D)TLS for an outgoing message. 495 When an application requests a session for a message, through the 496 cache, the application requests a security level for that session. 497 The TLS Transport Model MUST ensure that the (D)TLS session provides 498 security at least as high as the requested level of security. How 499 the security level is translated into the algorithms used to provide 500 data integrity and privacy is implementation-dependent. However, the 501 NULL integrity and encryption algorithms MUST NOT be used to fulfill 502 security level requests for authentication or privacy. 503 Implementations MAY choose to force (D)TLS to only allow 504 cipher_suites that provide both authentication and privacy to 505 guarantee this assertion. 507 If a suitable interface between the TLS Transport Model and the 508 (D)TLS Handshake Protocol is implemented to allow the selection of 509 security level dependent algorithms (for example a security level to 510 cipher_suites mapping table) then different security levels may be 511 utilized by the application. 513 The authentication, integrity and privacy algorithms used by the 514 (D)TLS Protocols may vary over time as the science of cryptography 515 continues to evolve and the development of (D)TLS continues over 516 time. Implementers are encouraged to plan for changes in operator 517 trust of particular algorithms and implementations should offer 518 configuration settings for mapping algorithms to SNMPv3 security 519 levels. 521 3.1.3. (D)TLS Sessions 523 (D)TLS sessions are opened by the TLS Transport Model during the 524 elements of procedure for an outgoing SNMP message. Since the sender 525 of a message initiates the creation of a (D)TLS session if needed, 526 the (D)TLS session will already exist for an incoming message. 528 Implementations MAY choose to instantiate (D)TLS sessions in 529 anticipation of outgoing messages. This approach might be useful to 530 ensure that a (D)TLS session to a given target can be established 531 before it becomes important to send a message over the (D)TLS 532 session. Of course, there is no guarantee that a pre-established 533 session will still be valid when needed. 535 DTLS sessions, when used over UDP, are uniquely identified within the 536 TLS Transport Model by the combination of transportDomain, 537 transportAddress, securityName, and requestedSecurityLevel associated 538 with each session. Each unique combination of these parameters MUST 539 have a locally-chosen unique tlsSessionID associated for active 540 sessions. For further information see Section 4.4 and Section 5. 541 TLS and DTLS over SCTP sessions, on the other hand, do not require a 542 unique pairing of attributes since their lower layer protocols (TCP 543 and SCTP) already provide adequate session framing. 545 3.2. Security Parameter Passing 547 For the (D)TLS server-side, (D)TLS-specific security parameters 548 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 549 are translated by the TLS Transport Model into security parameters 550 for the TLS Transport Model and security model (i.e., securityLevel, 551 securityName, transportDomain, transportAddress). The transport- 552 related and (D)TLS-security-related information, including the 553 authenticated identity, are stored in a cache referenced by 554 tmStateReference. 556 For the (D)TLS client-side, the TLS Transport Model takes input 557 provided by the dispatcher in the sendMessage() Abstract Service 558 Interface (ASI) and input from the tmStateReference cache. The 559 (D)TLS Transport Model converts that information into suitable 560 security parameters for (D)TLS and establishes sessions as needed. 562 The elements of procedure in Section 5 discuss these concepts in much 563 greater detail. 565 3.3. Notifications and Proxy 567 (D)TLS sessions may be initiated by (D)TLS clients on behalf of 568 command generators, notification originators or proxy forwarders. 569 Command generators are frequently operated by a human, but 570 notification originators and proxy forwarders are usually unmanned 571 automated processes. The targets to whom notifications should be 572 sent is typically determined and configured by a network 573 administrator. 575 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 576 management targets, including transportDomain, transportAddress, 577 securityName, securityModel, and securityLevel parameters, for 578 Notification Generator, Proxy Forwarder, and SNMP-controllable 579 Command Generator applications. Transport domains and transport 580 addresses are configured in the snmpTargetAddrTable, and the 581 securityModel, securityName, and securityLevel parameters are 582 configured in the snmpTargetParamsTable. This document defines a MIB 583 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 584 specify a (D)TLS client-side certificate to use for the connection. 586 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 587 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 588 set to the snmpTLSDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 589 object and an appropriate snmpTLSAddress, snmpDTLSUDPAddress or 590 snmpDTLSSCTPAddress value respectively. The snmpTargetParamsMPModel 591 column of the snmpTargetParamsTable should be set to a value of 3 to 592 indicate the SNMPv3 message processing model. The 593 snmpTargetParamsSecurityName should be set to an appropriate 594 securityName value and the tlstmParamsClientFingerprint parameter of 595 the tlstmParamsTable should be set a value that refers to a locally 596 held certificate to be used. The tlstmAddrServerFingerprint must be 597 set to a hash value that refers to a locally held copy of the 598 server's presented identity certificate. Other parameters, for 599 example cryptographic configuration such as cipher suites to use, 600 must come from configuration mechanisms not defined in this document. 601 The securityName defined in the snmpTargetParamsSecurityName column 602 will be used by the access control model to authorize any 603 notifications that need to be sent. 605 4. Elements of the Model 607 This section contains definitions required to realize the (D)TLS 608 Transport Model defined by this document. 610 4.1. X.509 Certificates 612 (D)TLS makes use of X.509 certificates for authentication of both 613 sides of the transport. This section discusses the use of 614 certificates in the TLSTM. A brief overview of X.509 certificate 615 infrastructure can be found in Appendix B. 617 4.1.1. Provisioning for the Certificate 619 Authentication using (D)TLS will require that SNMP entities are 620 provisioned with certificates, which are signed by trusted 621 certificate authorities. Furthermore, SNMP entities will most 622 commonly need to be provisioned with root certificates which 623 represent the list of trusted certificate authorities that an SNMP 624 entity can use for certificate verification. SNMP entities SHOULD 625 also be provisioned with a X.509 certificate revocation mechanism 626 which can be used to verify that a certificate has not been revoked. 627 The certificate trust anchors, being either CA certificates or public 628 keys for use by self-signed certificates, must be installed through 629 an out of band trusted mechanism into the server and its authenticity 630 MUST be verified before access is granted. 632 Having received a certificate, the authenticated tmSecurityName of 633 the principal is looked up using the tlstmCertToSNTable. This table 634 either: 636 o Maps a certificate's fingerprint type and value to a directly 637 specified tmSecurityName, or 639 o Identifies a certificate issuer's fingerprint and allows a child 640 certificate's subjectAltName or CommonName to be mapped to the 641 tmSecurityNome. 643 Implementations MAY choose to discard any connections for which no 644 potential tlstmCertToSNTable mapping exists before performing 645 certificate verification to avoid expending computational resources 646 associated with certificate verification. 648 The typical enterprise configuration will map a "subjectAltName" 649 component of the tbsCertificate to the TLSTM specific tmSecurityName. 650 The authenticated identity can be obtained by the TLS Transport Model 651 by extracting the subjectAltName(s) from the peer's certificate. The 652 receiving application will then have an appropriate tmSecurityName 653 for use by other SNMPv3 components like an access control model. 655 An example of this type of mapping setup can be found in Appendix C 657 This tmSecurityName may be later translated from a TLSTM specific 658 tmSecurityName to a SNMP engine securityName by the security model. 659 A security model, like the TSM security model [RFC5591], may perform 660 an identity mapping or a more complex mapping to derive the 661 securityName from the tmSecurityName offered by the TLS Transport 662 Model. 664 4.2. Messages 666 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 667 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 668 messages from being sent that exceeds the maximum DTLS message size. 669 The TLSTM implementation SHOULD return an error when the DTLS message 670 size would be exceeded and the message won't be sent. 672 4.3. SNMP Services 674 This section describes the services provided by the (D)TLS Transport 675 Model with their inputs and outputs. The services are between the 676 Transport Model and the dispatcher. 678 The services are described as primitives of an abstract service 679 interface (ASI) and the inputs and outputs are described as abstract 680 data elements as they are passed in these abstract service 681 primitives. 683 4.3.1. SNMP Services for an Outgoing Message 685 The dispatcher passes the information to the TLS Transport Model 686 using the ASI defined in the transport subsystem: 688 statusInformation = 689 sendMessage( 690 IN destTransportDomain -- transport domain to be used 691 IN destTransportAddress -- transport address to be used 692 IN outgoingMessage -- the message to send 693 IN outgoingMessageLength -- its length 694 IN tmStateReference -- reference to transport state 695 ) 697 The abstract data elements returned from or passed as parameters into 698 the abstract service primitives are as follows: 700 statusInformation: An indication of whether the passing of the 701 message was successful. If not, it is an indication of the 702 problem. 704 destTransportDomain: The transport domain for the associated 705 destTransportAddress. The Transport Model uses this parameter to 706 determine the transport type of the associated 707 destTransportAddress. This parameter may also be used by the 708 transport subsystem to route the message to the appropriate 709 Transport Model. This document specifies three TLS and DTLS based 710 Transport Domains for use: the snmpTLSDomain, the 711 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 713 destTransportAddress: The transport address of the destination TLS 714 Transport Model in a format specified by the SnmpTLSAddress, the 715 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTIONs. 717 outgoingMessage: The outgoing message to send to (D)TLS for 718 encapsulation. 720 outgoingMessageLength: The length of the outgoingMessage field. 722 tmStateReference: A handle/reference to tmSecurityData to be used 723 when securing outgoing messages. 725 4.3.2. SNMP Services for an Incoming Message 727 The TLS Transport Model processes the received message from the 728 network using the (D)TLS service and then passes it to the dispatcher 729 using the following ASI: 731 statusInformation = 732 receiveMessage( 733 IN transportDomain -- origin transport domain 734 IN transportAddress -- origin transport address 735 IN incomingMessage -- the message received 736 IN incomingMessageLength -- its length 737 IN tmStateReference -- reference to transport state 738 ) 740 The abstract data elements returned from or passed as parameters into 741 the abstract service primitives are as follows: 743 statusInformation: An indication of whether the passing of the 744 message was successful. If not, it is an indication of the 745 problem. 747 transportDomain: The transport domain for the associated 748 transportAddress. This document specifies three TLS and DTLS 749 based Transport Domains for use: the snmpTLSDomain, the 750 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 752 transportAddress: The transport address of the source of the 753 received message in a format specified by the SnmpTLSAddress, the 754 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 756 incomingMessage: The whole SNMP message after being processed by 757 (D)TLS and removed of the (D)TLS transport layer data. 759 incomingMessageLength: The length of the incomingMessage field. 761 tmStateReference: A handle/reference to tmSecurityData to be used by 762 the security model. 764 4.4. (D)TLS Services 766 This section describes the services provided by the (D)TLS Transport 767 Model with their inputs and outputs. These services are between the 768 TLS Transport Model and the (D)TLS transport layer. The following 769 sections describe services for establishing and closing a session and 770 for passing messages between the (D)TLS transport layer and the TLS 771 Transport Model. 773 4.4.1. Services for Establishing a Session 775 The TLS Transport Model provides the following ASI to describe the 776 data passed between the Transport Model and the (D)TLS transport 777 layer for session establishment. 779 statusInformation = -- errorIndication or success 780 openSession( 781 IN destTransportDomain -- transport domain to be used 782 IN destTransportAddress -- transport address to be used 783 IN securityName -- on behalf of this principal 784 IN securityLevel -- Level of Security requested 785 OUT tlsSessionID -- Session identifier for (D)TLS 786 ) 788 The abstract data elements returned from or passed as parameters into 789 the abstract service primitives are as follows: 791 statusInformation: An indication of whether the process was 792 successful or not. If not, then the status information will 793 include the error indication provided by (D)TLS. 795 destTransportDomain: The transport domain for the associated 796 destTransportAddress. The TLS Transport Model uses this parameter 797 to determine the transport type of the associated 798 destTransportAddress. This document specifies three TLS and DTLS 799 based Transport Domains for use: the snmpTLSDomain, the 800 snmpDTLSUDPDomain, and the snmpDTLSSCTPDomain. 802 destTransportAddress: The transport address of the destination TLS 803 Transport Model in a format specified by the SnmpTLSAddress, the 804 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 806 securityName: The security name representing the principal on whose 807 behalf the message will be sent. 809 securityLevel: The level of security requested by the application. 811 tlsSessionID: An implementation-dependent session identifier to 812 reference the specific (D)TLS session. 814 Neither DTLS or UDP provides a session de-multiplexing mechanism and 815 it is possible that implementations will only be able to identify a 816 unique session based on a unique combination of source address, 817 destination address, source UDP port number and destination UDP port 818 number. Because of this, when establishing a new sessions 819 implementations MUST use a different UDP source port number for each 820 connection to a given remote destination IP-address/port-number 821 combination to ensure the remote entity can properly disambiguate 822 between multiple sessions from a host to the same port on a server. 823 TLS and DTLS over SCTP provide session de-multiplexing so this 824 restriction is not needed for TLS or DTLS over SCTP implementations. 826 The procedural details for establishing a session are further 827 described in Section 5.3. 829 Upon completion of the process the TLS Transport Model returns status 830 information and, if the process was successful the tlsSessionID for 831 the session. Other implementation-dependent data from (D)TLS may 832 also be returned. The tlsSessionID is formatted and stored in an 833 implementation-dependent manner. It is tied to the tmSecurityData 834 for future use of this session and must remain constant and unique 835 while the session is open. 837 4.4.2. (D)TLS Services for an Incoming Message 839 When the TLS Transport Model invokes the (D)TLS record layer to 840 verify proper security for the incoming message, it must use the 841 following ASI: 843 statusInformation = -- errorIndication or success 844 tlsRead( 845 IN tlsSessionID -- Session identifier for (D)TLS 846 IN wholeTlsMsg -- as received on the wire 847 IN wholeTlsMsgLength -- length as received on the wire 848 OUT incomingMessage -- the whole SNMP message from (D)TLS 849 OUT incomingMessageLength -- the length of the SNMP message 850 ) 852 The abstract data elements returned from or passed as parameters into 853 the abstract service primitives are as follows: 855 statusInformation: An indication of whether the process was 856 successful or not. If not, then the status information will 857 include the error indication provided by (D)TLS. 859 tlsSessionID: An implementation-dependent session identifier to 860 reference the specific (D)TLS session. How the (D)TLS session ID 861 is obtained for each message is implementation-dependent. As an 862 implementation hint for DTLS over UDP, the TLS Transport Model 863 might examine incoming messages to determine the source IP 864 address, source port number, destination IP address, and 865 destination port number and use these values to look up the local 866 tlsSessionID in the list of active sessions. 868 wholeDtlsMsg: The whole message as received on the wire. 870 wholeDtlsMsgLength: The length of the wholeDtlsMsg field. 872 incomingMessage: The whole SNMP message after being processed by 873 (D)TLS and removed of the (D)TLS transport layer data. 875 incomingMessageLength: The length of the incomingMessage field. 877 4.4.3. (D)TLS Services for an Outgoing Message 879 When the TLS Transport Model invokes the (D)TLS record layer to 880 encapsulate and transmit a SNMP message, it must use the following 881 ASI. 883 statusInformation = -- errorIndication or success 884 tlsWrite( 885 IN tlsSessionID -- Session identifier for (D)TLS 886 IN outgoingMessage -- the message to send 887 IN outgoingMessageLength -- its length 888 ) 889 The abstract data elements returned from or passed as parameters into 890 the abstract service primitives are as follows: 892 statusInformation: An indication of whether the process was 893 successful or not. If not, then the status information will 894 include the error indication provided by (D)TLS. 896 tlsSessionID: An implementation-dependent session identifier to 897 reference the specific (D)TLS session that the message should be 898 sent using. 900 outgoingMessage: The outgoing message to send to (D)TLS for 901 encapsulation. 903 outgoingMessageLength: The length of the outgoingMessage field. 905 4.5. Cached Information and References 907 When performing SNMP processing, there are two levels of state 908 information that may need to be retained: the immediate state linking 909 a request-response pair, and potentially longer-term state relating 910 to transport and security. "Transport Subsystem for the Simple 911 Network Management Protocol" [RFC5590] defines general requirements 912 for caches and references. 914 4.5.1. TLS Transport Model Cached Information 916 The TLSTM has no specific responsibilities regarding the cached 917 information beyond those discussed in "Transport Subsystem for the 918 Simple Network Management Protocol" [RFC5590] 920 5. Elements of Procedure 922 Abstract service interfaces have been defined by [RFC3411] and 923 further augmented by [RFC5590] to describe the conceptual data flows 924 between the various subsystems within an SNMP entity. The TLSTM uses 925 some of these conceptual data flows when communicating between 926 subsystems. 928 To simplify the elements of procedure, the release of state 929 information is not always explicitly specified. As a general rule, 930 if state information is available when a message gets discarded, the 931 message-state information should also be released. If state 932 information is available when a session is closed, the session state 933 information should also be released. Sensitive information, like 934 cryptographic keys, should be overwritten appropriately first prior 935 to being released. 937 An error indication in statusInformation will typically include the 938 Object Identifier (OID) and value for an incremented error counter. 939 This may be accompanied by the requested securityLevel and the 940 tmStateReference. Per-message context information is not accessible 941 to Transport Models, so for the returned counter OID and value, 942 contextEngine would be set to the local value of snmpEngineID and 943 contextName to the default context for error counters. 945 5.1. Procedures for an Incoming Message 947 This section describes the procedures followed by the (D)TLS 948 Transport Model when it receives a (D)TLS protected packet. The 949 steps are broken into two different sections. Section 5.1.1 950 describes the needed steps for de-multiplexing multiple DTLS 951 sessions, which is specifically needed for DTLS over UDP sessions. 952 Section 5.1.2 describes the steps specific to transport processing 953 once the (D)TLS processing has been completed. It is assumed that 954 TLS and DTLS/SCP protocol implementations already provide appropriate 955 message demultiplexing and only the processing steps in Section 5.1.2 956 are needed. 958 5.1.1. DTLS Processing for Incoming Messages 960 DTLS is significantly different in terms of session handling than 961 when TLS or DTLS is run over session based streaming protocols like 962 TCP or SCTP. Specifically, the DTLS protocol, when run over UDP, 963 does not have a session identifier that allows implementations to 964 determine through what session a packet arrived. DTLS over SCTP and 965 TLS over TCP streams have built in session demultiplexing and thus 966 the steps in this section are not necessary for those protocol 967 combinations. It is always critical, however, that implementations 968 be able to derive a tlsSessionID from any session demultiplexing 969 process. 971 A process for demultiplexing multiple DTLS sessions arriving over UDP 972 must be incorporated into the procedures for processing an incoming 973 message. The steps in this section describe one possible method to 974 accomplish this, although any implementation dependent method should 975 be suitable as long as the results are consistently deterministic. 976 The important output results from the steps in this process are the 977 transportDomain, the transportAddress, the wholeMessage, the 978 wholeMessageLength, and a unique implementation-dependent session 979 identifier (tlsSessionID). 981 This demultiplexing procedure assumes that upon session establishment 982 an entry in a local transport mapping table is created in the 983 Transport Model's Local Configuration Datastore (LCD). The transport 984 mapping table's entry should map a unique combination of the remote 985 address, remote port number, local address and local port number to 986 an implementation-dependent tlsSessionID. 988 1) The TLS Transport Model examines the raw UDP message, in an 989 implementation-dependent manner. If the message is not a DTLS 990 message then it should be discarded. If the message is not a 991 (D)TLS Application Data message (such as a session initialization 992 or session modification message) then the message should be 993 processed by the underlying DTLS framework and no further steps 994 below should be taken by the DTLS Transport. 996 2) The TLS Transport Model queries the LCD using the transport 997 parameters (source and destination addresses and ports) to 998 determine if a session already exists and its tlsSessionID. 1000 3) If a matching entry in the LCD does not exist then the message is 1001 discarded. Increment the tlstmSessionNoAvailableSessions counter 1002 and stop processing the message. 1004 Note that an entry would already exist if the client and server's 1005 session establishment procedures had been successfully completed 1006 (as described both above and in Section 5.3) even if no message 1007 had yet been sent through the newly established session. An 1008 entry may not exist, however, if a "rogue" message was routed to 1009 the SNMP entity by mistake. An entry might also be missing 1010 because of a "broken" session (see operational considerations). 1012 4) Retrieve the tlsSessionID from the LCD. 1014 5) The tlsWholeMsg, and the tlsSessionID are passed to DTLS for 1015 integrity checking and decryption using the tlsRead() ASI. 1017 6) If the message fails integrity checks or other (D)TLS security 1018 processing then increment the tlstmDTLSProtectionErrors counter, 1019 discard and stop processing the message. 1021 7) The output of the tlsRead ASI results in an incomingMessage and 1022 an incomingMessageLength. These results and the tlsSessionID are 1023 used below in the Section 5.1.2 to complete the processing of the 1024 incoming message. 1026 5.1.2. Transport Processing for Incoming Messages 1028 The procedures in this section describe how the TLS Transport Model 1029 should process messages that have already been properly extracted 1030 from the (D)TLS stream. 1032 Create a tmStateReference cache for the subsequent reference and 1033 assign the following values within it: 1035 tmTransportDomain = snmpTLSDomain, snmpDTLSUDPDomain or 1036 snmpDTLSSCTPDomain as appropriate. 1038 tmTransportAddress = The address the message originated from, 1039 determined in an implementation dependent way. 1041 tmSecurityLevel = The derived tmSecurityLevel for the session, as 1042 discussed in Section 3.1.2 and Section 5.3. 1044 tmSecurityName = The derived tmSecurityName for the session as 1045 discussed in Section 5.3. This value MUST be constant during the 1046 lifetime of the (D)TLS session. 1048 tmSessionID = The tlsSessionID, which MUST be a unique session 1049 identifier for this (D)TLS session. The contents and format of 1050 this identifier are implementation dependent as long as it is 1051 unique to the session. A session identifier MUST NOT be reused 1052 until all references to it are no longer in use. The tmSessionID 1053 is equal to the tlsSessionID discussed in Section 5.1.1. 1054 tmSessionID refers to the session identifier when stored in the 1055 tmStateReference and tlsSessionID refers to the session identifier 1056 when stored in the LCD. They MUST always be equal when processing 1057 a given session's traffic. 1059 The wholeMessage and the wholeMessageLength are assigned values from 1060 the incomingMessage and incomingMessageLength values from the (D)TLS 1061 processing. 1063 The TLS Transport Model passes the transportDomain, transportAddress, 1064 wholeMessage, and wholeMessageLength to the dispatcher using the 1065 receiveMessage ASI: 1067 statusInformation = 1068 receiveMessage( 1069 IN transportDomain -- snmpTLSDomain, snmpDTLSUDPDomain, 1070 -- or snmpDTLSSCTPDomain 1071 IN transportAddress -- address for the received message 1072 IN wholeMessage -- the whole SNMP message from (D)TLS 1073 IN wholeMessageLength -- the length of the SNMP message 1074 IN tmStateReference -- transport info 1075 ) 1077 5.2. Procedures for an Outgoing Message 1079 The dispatcher sends a message to the TLS Transport Model using the 1080 following ASI: 1082 statusInformation = 1083 sendMessage( 1084 IN destTransportDomain -- transport domain to be used 1085 IN destTransportAddress -- transport address to be used 1086 IN outgoingMessage -- the message to send 1087 IN outgoingMessageLength -- its length 1088 IN tmStateReference -- transport info 1089 ) 1091 This section describes the procedure followed by the TLS Transport 1092 Model whenever it is requested through this ASI to send a message. 1094 1) Extract the tmSessionID, tmTransportAddress, tmSecurityName, 1095 tmRequestedSecurityLevel, and tmSameSecurity values from the 1096 tmStateReference. Note: The tmSessionID value may be undefined 1097 if no session exists yet over which the message can be sent. 1099 2) If tmSameSecurity is true and either tmSessionID is undefined or 1100 refers to a session that is no longer open then increment the 1101 tlstmSessionNoAvailableSessions counter, discard the message and 1102 return the error indication in the statusInformation. Processing 1103 of this message stops. 1105 3) If tmSameSecurity is false and tmSessionID refers to a session 1106 that is no longer available then an implementation SHOULD open a 1107 new session using the openSession() ASI (described in greater 1108 detail in step 4b). An implementation MAY choose to return an 1109 error to the calling module and stop processing of the message. 1111 4) If tmSessionID is undefined, then use tmTransportAddress, 1112 tmSecurityName and tmRequestedSecurityLevel to see if there is a 1113 corresponding entry in the LCD suitable to send the message over. 1115 4a) If there is a corresponding LCD entry, then this session 1116 will be used to send the message. 1118 4b) If there is not a corresponding LCD entry, then open a 1119 session using the openSession() ASI (discussed further in 1120 Section 4.4.1). Implementations MAY wish to offer message 1121 buffering to prevent redundant openSession() calls for the 1122 same cache entry. If an error is returned from 1123 OpenSession(), then discard the message, increment the 1124 tlstmSessionOpenErrors, return an error indication to the 1125 calling module and stop processing of the message. 1127 5) Using either the session indicated by the tmSessionID if there 1128 was one or the session resulting from a previous step (3 or 4), 1129 pass the outgoingMessage to (D)TLS for encapsulation and 1130 transmission. 1132 5.3. Establishing a Session 1134 The TLS Transport Model provides the following primitive to establish 1135 a new (D)TLS session (previously discussed in Section 4.4.1): 1137 statusInformation = -- errorIndication or success 1138 openSession( 1139 IN destTransportDomain -- transport domain to be used 1140 IN destTransportAddress -- transport address to be used 1141 IN securityName -- on behalf of this principal 1142 IN securityLevel -- Level of Security requested 1143 OUT tlsSessionID -- Session identifier for (D)TLS 1144 ) 1146 The following describes the procedure to follow when establishing a 1147 SNMP over (D)TLS session between SNMP engines for exchanging SNMP 1148 messages. This process is followed by any SNMP engine establishing a 1149 session for subsequent use. 1151 This MAY be done automatically for SNMP messages which are not 1152 Response or Report messages. 1154 1) The client selects the appropriate certificate and cipher_suites 1155 for the key agreement based on the tmSecurityName and the 1156 tmRequestedSecurityLevel for the session. For sessions being 1157 established as a result of a SNMP-TARGET-MIB based operation, the 1158 certificate will potentially have been identified via the 1159 tlstmParamsTable mapping and the cipher_suites will have to be 1160 taken from system-wide or implementation-specific configuration. 1161 Otherwise, the certificate and appropriate cipher_suites will 1162 need to be passed to the openSession() ASI as supplemental 1163 information or configured through an implementation-dependent 1164 mechanism. It is also implementation-dependent and possibly 1165 policy-dependent how tmRequestedSecurityLevel will be used to 1166 influence the security capabilities provided by the (D)TLS 1167 session. However this is done, the security capabilities 1168 provided by (D)TLS MUST be at least as high as the level of 1169 security indicated by the tmRequestedSecurityLevel parameter. 1170 The actual security level of the session is reported in the 1171 tmStateReference cache as tmSecurityLevel. For (D)TLS to provide 1172 strong authentication, each principal acting as a Command 1173 Generator SHOULD have its own certificate. 1175 2) Using the destTransportDomain and destTransportAddress values, 1176 the client will initiate the (D)TLS handshake protocol to 1177 establish session keys for message integrity and encryption. 1179 If the attempt to establish a session is unsuccessful, then 1180 tlstmSessionOpenErrors is incremented, an error indication is 1181 returned, and processing stops. 1183 3) Once a (D)TLS secured session is established and both sides have 1184 performed any appropriate certificate authentication verification 1185 (e.g. [RFC5280]) then each side will determine and/or check the 1186 identity of the remote entity using the procedures described 1187 below. 1189 a) The (D)TLS server side of the connection identifies the 1190 authenticated identity from the (D)TLS client's principal 1191 certificate using configuration information from the 1192 tlstmCertToSNTable mapping table. The resulting derived 1193 securityName is recorded in the tmStateReference cache as 1194 tmSecurityName. The details of the lookup process are fully 1195 described in the DESCRIPTION clause of the tlstmCertToSNTable 1196 MIB object. If any verification fails in any way (for 1197 example because of failures in cryptographic verification or 1198 because of the lack of an appropriate row in the 1199 tlstmCertToSNTable) then the session establishment MUST fail, 1200 the tlstmSessionInvalidClientCertificates object is 1201 incremented and processing stops. 1203 b) The (D)TLS client side of the connection MUST verify that 1204 authenticated identity of the (D)TLS server's certificate is 1205 the certificate expected. This can be done using the 1206 configuration fingerprints found in the tlstmAddrTable if the 1207 client is establishing the connection based on SNMP-TARGET- 1208 MIB configuration or based on external certificate path 1209 validation processes (e.g. [RFC5280]). 1211 Methods for verifying that the proper destination was reached 1212 based on the presented certificate are described in 1213 [I-D.saintandre-tls-server-id-check]. Matching the server's 1214 naming against SubjectAltName extension values SHOULD be the 1215 preferred mechanism for comparison, but matching the 1216 CommonName MAY be used. 1218 (D)TLS provides assurance that the authenticated identity has 1219 been signed by a trusted configured certificate authority. 1221 If verification of the server's certificate fails in any way 1222 (for example because of failures in cryptographic 1223 verification or the presented identity was not the expected 1224 identity) then the session establishment MUST fail, the 1225 tlstmSessionInvalidServerCertificates object is incremented 1226 and processing stops. 1228 4) The (D)TLS-specific session identifier is passed to the TLS 1229 Transport Model and associated with the tmStateReference cache 1230 entry to indicate that the session has been established 1231 successfully and to point to a specific (D)TLS session for future 1232 use. 1234 (D)TLS provides no explicit manner for transmitting an identity the 1235 client wishes to connect to during or prior to key exchange to 1236 facilitate certificate selection at the server (e.g. at a 1237 Notification Receiver). I.E., there is no available mechanism for 1238 sending notifications to a specific principal at a given TCP, UDP or 1239 SCTP port. Therefore, an implementation that wishes to support 1240 multiple identities MAY use separate TCP, UDP or SCTP port numbers to 1241 indicate the desired principal or some other implementation-dependent 1242 solution. 1244 5.4. Closing a Session 1246 The TLS Transport Model provides the following primitive to close a 1247 session: 1249 statusInformation = 1250 closeSession( 1251 IN tmStateReference -- transport info 1252 ) 1254 The following describes the procedure to follow to close a session 1255 between a client and server. This process is followed by any SNMP 1256 engine closing the corresponding SNMP session. 1258 1) Look up the session in the cache and the LCD using the 1259 tmStateReference and its contents. 1261 2) If there is no session open associated with the tmStateReference, 1262 then closeSession processing is completed. 1264 3) Delete the entry from the cache and any other implementation- 1265 dependent information in the LCD. 1267 4) Have (D)TLS close the specified session. This SHOULD include 1268 sending a close_notify TLS Alert to inform the other side that 1269 session cleanup may be performed. 1271 6. MIB Module Overview 1273 This MIB module provides management of the TLS Transport Model. It 1274 defines needed textual conventions, statistical counters, 1275 notifications and configuration infrastructure necessary for session 1276 establishment. Example usage of the configuration tables can be 1277 found in Appendix C. 1279 6.1. Structure of the MIB Module 1281 Objects in this MIB module are arranged into subtrees. Each subtree 1282 is organized as a set of related objects. The overall structure and 1283 assignment of objects to their subtrees, and the intended purpose of 1284 each subtree, is shown below. 1286 6.2. Textual Conventions 1288 Generic and Common Textual Conventions used in this module can be 1289 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1291 This module defines the following new Textual Conventions: 1293 o New TransportDomain and TransportAddress formats for describing 1294 (D)TLS connection addressing requirements. 1296 o Public certificate fingerprint allowing MIB module objects to 1297 generically refer to a stored X.509 certificate using a 1298 cryptographic hash as a reference pointer. 1300 6.3. Statistical Counters 1302 The TLSTM-MIB defines some statical counters that can provide network 1303 managers with feedback about (D)TLS session usage and potential 1304 errors that a MIB-instrumented device may be experiencing. 1306 6.4. Configuration Tables 1308 The TLSTM-MIB defines configuration tables that a manager can use for 1309 configuring a MIB-instrumented device for sending and receiving SNMP 1310 messages over (D)TLS. In particular, there is are MIB tables that 1311 extend the SNMP-TARGET-MIB for configuring (D)TLS certificate usage 1312 and a MIB table for mapping incoming (D)TLS client certificates to 1313 SNMPv3 securityNames. 1315 6.4.1. Notifications 1317 The TLSTM-MIB defines notifications to alert management stations when 1318 a (D)TLS connection fails because the server's presented certificate 1319 did not meet an expected value, according to the tlstmAddrTable. 1321 6.5. Relationship to Other MIB Modules 1323 Some management objects defined in other MIB modules are applicable 1324 to an entity implementing the TLS Transport Model. In particular, it 1325 is likely that an entity implementing the TLSTM-MIB will implement 1326 the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], the SNMP- 1327 TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] and the 1328 SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1330 The TLSTM-MIB module contained in this document is for managing TLS 1331 Transport Model information. 1333 6.5.1. MIB Modules Required for IMPORTS 1335 The TLSTM-MIB module imports items from SNMPv2-SMI [RFC2578], 1336 SNMPv2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1337 [RFC3413] and SNMPv2-CONF [RFC2580]. 1339 7. MIB Module Definition 1341 TLSTM-MIB DEFINITIONS ::= BEGIN 1343 IMPORTS 1344 MODULE-IDENTITY, OBJECT-TYPE, 1345 OBJECT-IDENTITY, snmpModules, snmpDomains, 1346 Counter32, Unsigned32, NOTIFICATION-TYPE 1347 FROM SNMPv2-SMI 1348 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType 1349 FROM SNMPv2-TC 1350 MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP 1351 FROM SNMPv2-CONF 1352 SnmpAdminString 1353 FROM SNMP-FRAMEWORK-MIB 1354 snmpTargetParamsName, snmpTargetAddrName 1355 FROM SNMP-TARGET-MIB 1356 ; 1358 tlstmMIB MODULE-IDENTITY 1359 LAST-UPDATED "200807070000Z" 1360 ORGANIZATION "ISMS Working Group" 1361 CONTACT-INFO "WG-EMail: isms@lists.ietf.org 1362 Subscribe: isms-request@lists.ietf.org 1364 Chairs: 1365 Juergen Schoenwaelder 1366 Jacobs University Bremen 1367 Campus Ring 1 1368 28725 Bremen 1369 Germany 1370 +49 421 200-3587 1371 j.schoenwaelder@jacobs-university.de 1373 Russ Mundy 1374 SPARTA, Inc. 1375 7110 Samuel Morse Drive 1376 Columbia, MD 21046 1377 USA 1379 Co-editors: 1380 Wes Hardaker 1381 Sparta, Inc. 1382 P.O. Box 382 1383 Davis, CA 95617 1384 USA 1385 ietf@hardakers.net 1386 " 1388 DESCRIPTION " 1389 The TLS Transport Model MIB 1391 Copyright (c) 2009 IETF Trust and the persons 1392 identified as authors of the code. All rights reserved. 1394 Redistribution and use in source and binary forms, with or 1395 without modification, are permitted provided that the 1396 following conditions are met: 1398 - Redistributions of source code must retain the above copyright 1399 notice, this list of conditions and the following disclaimer. 1401 - Redistributions in binary form must reproduce the above 1402 copyright notice, this list of conditions and the following 1403 disclaimer in the documentation and/or other materials 1404 provided with the distribution. 1406 - Neither the name of Internet Society, IETF or IETF Trust, 1407 nor the names of specific contributors, may be used to endorse 1408 or promote products derived from this software without 1409 specific prior written permission. 1411 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 1412 CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, 1413 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 1414 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 1415 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 1416 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 1418 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 1419 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 1420 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 1421 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 1422 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 1423 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 1424 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 1426 This version of this MIB module is part of RFC XXXX; 1427 see the RFC itself for full legal notices." 1429 -- NOTE to RFC editor: replace XXXX with actual RFC number 1430 -- for this document and remove this note 1432 REVISION "200807070000Z" 1433 DESCRIPTION "The initial version, published in RFC XXXX." 1434 -- NOTE to RFC editor: replace XXXX with actual RFC number 1435 -- for this document and remove this note 1437 ::= { snmpModules xxxx } 1438 -- RFC Ed.: replace xxxx with IANA-assigned number and 1439 -- remove this note 1441 -- ************************************************ 1442 -- subtrees of the TLSTM-MIB 1443 -- ************************************************ 1445 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1446 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1447 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1449 -- ************************************************ 1450 -- tlstmObjects - Objects 1451 -- ************************************************ 1453 snmpTLSDomain OBJECT-IDENTITY 1454 STATUS current 1455 DESCRIPTION 1456 "The SNMP over TLS transport domain. The corresponding 1457 transport address is of type SnmpTLSAddress. 1459 The securityName prefix to be associated with the 1460 snmpTLSDomain is 'tls'. This prefix may be used by 1461 security models or other components to identify which secure 1462 transport infrastructure authenticated a securityName." 1464 ::= { snmpDomains xx } 1466 -- RFC Ed.: replace xx with IANA-assigned number and 1467 -- remove this note 1469 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1470 -- if 'tls' is not assigned to this document. 1472 snmpDTLSUDPDomain OBJECT-IDENTITY 1473 STATUS current 1474 DESCRIPTION 1475 "The SNMP over DTLS/UDP transport domain. The corresponding 1476 transport address is of type SnmpDTLSUDPAddress. 1478 When an SNMP entity uses the snmpDTLSUDPDomain transport 1479 model, it must be capable of accepting messages up to 1480 the maximum MTU size for an interface it supports, minus the 1481 needed IP, UDP, DTLS and other protocol overheads. 1483 The securityName prefix to be associated with the 1484 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1485 security models or other components to identify which secure 1486 transport infrastructure authenticated a securityName." 1488 ::= { snmpDomains yy } 1490 -- RFC Ed.: replace yy with IANA-assigned number and 1491 -- remove this note 1493 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1494 -- if 'dtls' is not assigned to this document. 1496 snmpDTLSSCTPDomain OBJECT-IDENTITY 1497 STATUS current 1498 DESCRIPTION 1499 "The SNMP over DTLS/SCTP transport domain. The corresponding 1500 transport address is of type SnmpDTLSSCTPAddress. 1502 The securityName prefix to be associated with the 1503 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1504 security models or other components to identify which secure 1505 transport infrastructure authenticated a securityName." 1507 ::= { snmpDomains zz } 1509 -- RFC Ed.: replace zz with IANA-assigned number and 1510 -- remove this note 1512 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1513 -- if 'dtls' is not assigned to this document. 1515 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1516 DISPLAY-HINT "1a" 1517 STATUS current 1518 DESCRIPTION 1519 "Represents a TCP connection address for an IPv4 address, an 1520 IPv6 address or an US-US-ASCII encoded hostname and port number. 1522 An IPv4 address must be in dotted decimal format followed by a 1523 colon ':' (US-ASCII character 0x3A) and a decimal port number 1524 in US-ASCII. 1526 An IPv6 address must be a colon separated format, surrounded 1527 by square brackets ('[', US-ASCII character 0x5B, and ']', 1528 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1529 character 0x3A) and a decimal port number in US-ASCII. 1531 A hostname is always in US-US-ASCII (as per RFC1033); 1532 internationalized hostnames are encoded in US-US-ASCII as 1533 specified in RFC 3490. The hostname is followed by a colon 1534 ':' (US-US-ASCII character 0x3A) and a decimal port number in 1535 US-US-ASCII. The name SHOULD be fully qualified whenever 1536 possible. 1538 Values of this textual convention may not be directly usable 1539 as transport-layer addressing information, and may require 1540 run-time resolution. As such, applications that write them 1541 must be prepared for handling errors if such values are not 1542 supported, or cannot be resolved (if resolution occurs at the 1543 time of the management operation). 1545 The DESCRIPTION clause of TransportAddress objects that may 1546 have snmpTLSAddress values must fully describe how (and 1547 when) such names are to be resolved to IP addresses and vice 1548 versa. 1550 This textual convention SHOULD NOT be used directly in object 1551 definitions since it restricts addresses to a specific 1552 format. However, if it is used, it MAY be used either on its 1553 own or in conjunction with TransportAddressType or 1554 TransportDomain as a pair. 1556 When this textual convention is used as a syntax of an index 1557 object, there may be issues with the limit of 128 1558 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1559 that all MIB documents using this textual convention make 1560 explicit any limitations on index component lengths that 1561 management software must observe. This may be done either by 1562 including SIZE constraints on the index components or by 1563 specifying applicable constraints in the conceptual row 1564 DESCRIPTION clause or in the surrounding documentation." 1565 REFERENCE 1566 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1567 RFC 3490: Internationalizing Domain Names in Applications 1568 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1569 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1570 " 1571 SYNTAX OCTET STRING (SIZE (1..255)) 1573 SnmpDTLSUDPAddress ::= TEXTUAL-CONVENTION 1574 DISPLAY-HINT "1a" 1575 STATUS current 1576 DESCRIPTION 1577 "Represents a UDP connection address for an IPv4 address, an 1578 IPv6 address or an US-ASCII encoded hostname and port number. 1580 An IPv4 address must be a dotted decimal format followed by a 1581 colon ':' (US-ASCII character 0x3A) and a decimal port number in 1582 US-ASCII. 1584 An IPv6 address must be a colon separated format, surrounded 1585 by square brackets ('[', US-ASCII character 0x5B, and ']', 1586 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1587 character 0x3A) and a decimal port number in US-ASCII. 1589 A hostname is always in US-US-ASCII (as per RFC1033); 1590 internationalized hostnames are encoded in US-US-ASCII as 1591 specified in RFC 3490. The hostname is followed by a colon 1592 ':' (US-US-ASCII character 0x3A) and a decimal port number in 1593 US-US-ASCII. The name SHOULD be fully qualified whenever 1594 possible. 1596 Values of this textual convention may not be directly usable 1597 as transport-layer addressing information, and may require 1598 run-time resolution. As such, applications that write them 1599 must be prepared for handling errors if such values are not 1600 supported, or cannot be resolved (if resolution occurs at the 1601 time of the management operation). 1603 The DESCRIPTION clause of TransportAddress objects that may 1604 have snmpDTLSUDPAddress values must fully describe how (and 1605 when) such names are to be resolved to IP addresses and vice 1606 versa. 1608 This textual convention SHOULD NOT be used directly in object 1609 definitions since it restricts addresses to a specific 1610 format. However, if it is used, it MAY be used either on its 1611 own or in conjunction with TransportAddressType or 1612 TransportDomain as a pair. 1614 When this textual convention is used as a syntax of an index 1615 object, there may be issues with the limit of 128 1616 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1617 that all MIB documents using this textual convention make 1618 explicit any limitations on index component lengths that 1619 management software must observe. This may be done either by 1620 including SIZE constraints on the index components or by 1621 specifying applicable constraints in the conceptual row 1622 DESCRIPTION clause or in the surrounding documentation." 1623 REFERENCE 1624 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1625 RFC 3490: Internationalizing Domain Names in Applications 1626 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1627 RFC 4347: Datagram Transport Layer Security 1628 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1629 " 1630 SYNTAX OCTET STRING (SIZE (1..255)) 1632 SnmpDTLSSCTPAddress ::= TEXTUAL-CONVENTION 1633 DISPLAY-HINT "1a" 1634 STATUS current 1635 DESCRIPTION 1636 "Represents a SCTP connection address for an IPv4 address, an 1637 IPv6 address or an US-ASCII encoded hostname and port number. 1639 An IPv4 address must be a dotted decimal format followed by a 1640 colon ':' (US-ASCII character 0x3A) and a decimal port number in 1641 US-ASCII. 1643 An IPv6 address must be a colon separated format, surrounded 1644 by square brackets ('[', US-ASCII character 0x5B, and ']', 1645 US-ASCII character 0x5D), followed by a colon ':' (US-ASCII 1646 character 0x3A) and a decimal port number in US-ASCII. 1648 A hostname is always in US-US-ASCII (as per RFC1033); 1649 internationalized hostnames are encoded in US-US-ASCII as 1650 specified in RFC 3490. The hostname is followed by a colon 1651 ':' (US-US-ASCII character 0x3A) and a decimal port number in 1652 US-US-ASCII. The name SHOULD be fully qualified whenever 1653 possible. 1655 Values of this textual convention may not be directly usable 1656 as transport-layer addressing information, and may require 1657 run-time resolution. As such, applications that write them 1658 must be prepared for handling errors if such values are not 1659 supported, or cannot be resolved (if resolution occurs at the 1660 time of the management operation). 1662 The DESCRIPTION clause of TransportAddress objects that may 1663 have snmpDTLSSCTPAddress values must fully describe how (and 1664 when) such names are to be resolved to IP addresses and vice 1665 versa. 1667 This textual convention SHOULD NOT be used directly in object 1668 definitions since it restricts addresses to a specific 1669 format. However, if it is used, it MAY be used either on its 1670 own or in conjunction with TransportAddressType or 1671 TransportDomain as a pair. 1673 When this textual convention is used as a syntax of an index 1674 object, there may be issues with the limit of 128 1675 sub-identifiers specified in SMIv2 (STD 58). It is RECOMMENDED 1676 that all MIB documents using this textual convention make 1677 explicit any limitations on index component lengths that 1678 management software must observe. This may be done either by 1679 including SIZE constraints on the index components or by 1680 specifying applicable constraints in the conceptual row 1681 DESCRIPTION clause or in the surrounding documentation." 1682 SYNTAX OCTET STRING (SIZE (1..255)) 1684 Fingerprint ::= TEXTUAL-CONVENTION 1685 DISPLAY-HINT "1x:254x" 1686 STATUS current 1687 DESCRIPTION 1688 "A Fingerprint value that can be used to uniquely reference 1689 other data of potentially arbitrary length. 1691 A Fingerprint value is composed of a 1-octet hashing algorithm 1692 type. The octet value encoded is taken from the IANA TLS 1693 HashAlgorithm Registry (RFC5246). The remaining octets are 1694 filled using the results of the hashing algorithm. 1696 This TEXTUAL-CONVENTION SHOULD NOT be used as a form of 1697 cryptographic verification and a data source with a matching 1698 fingerprint should not be considered authenticated because the 1699 value matches. This TEXTUAL-CONVENTION is only intended for 1700 use as a reference to a stored copy of a longer data source. 1701 The contents of full data source referenced by this fingerprint 1702 needs to be compared against to assure collisions have not 1703 resulted." 1704 REFERENCE 1705 "RFC 1033: DOMAIN ADMINISTRATORS OPERATIONS GUIDE 1706 RFC 3490: Internationalizing Domain Names in Applications 1707 RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1708 RFC 4347: Datagram Transport Layer Security 1709 RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 1710 " 1711 SYNTAX OCTET STRING (SIZE (1..255)) 1713 -- The tlstmSession Group 1715 tlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1717 tlstmSessionOpens OBJECT-TYPE 1718 SYNTAX Counter32 1719 MAX-ACCESS read-only 1720 STATUS current 1721 DESCRIPTION 1722 "The number of times an openSession() request has been 1723 executed as an (D)TLS client, whether it succeeded or failed." 1724 ::= { tlstmSession 1 } 1726 tlstmSessionCloses OBJECT-TYPE 1727 SYNTAX Counter32 1728 MAX-ACCESS read-only 1729 STATUS current 1730 DESCRIPTION 1731 "The number of times a closeSession() request has been 1732 executed as an (D)TLS client, whether it succeeded or failed." 1733 ::= { tlstmSession 2 } 1735 tlstmSessionOpenErrors OBJECT-TYPE 1736 SYNTAX Counter32 1737 MAX-ACCESS read-only 1738 STATUS current 1739 DESCRIPTION 1740 "The number of times an openSession() request failed to open a 1741 session as a (D)TLS client, for any reason." 1743 ::= { tlstmSession 3 } 1745 tlstmSessionNoAvailableSessions OBJECT-TYPE 1746 SYNTAX Counter32 1747 MAX-ACCESS read-only 1748 STATUS current 1749 DESCRIPTION 1750 "The number of times an outgoing message was dropped because 1751 the session associated with the passed tmStateReference was no 1752 longer (or was never) available." 1753 ::= { tlstmSession 4 } 1755 tlstmSessionInvalidClientCertificates OBJECT-TYPE 1756 SYNTAX Counter32 1757 MAX-ACCESS read-only 1758 STATUS current 1759 DESCRIPTION 1760 "The number of times an incoming session was not established 1761 on an (D)TLS server because the presented client certificate was 1762 invalid. Reasons for invalidation includes, but is not 1763 limited to, cryptographic validation failures and lack of a 1764 suitable mapping row in the tlstmCertToSNTable." 1765 ::= { tlstmSession 5 } 1767 tlstmSessionInvalidServerCertificates OBJECT-TYPE 1768 SYNTAX Counter32 1769 MAX-ACCESS read-only 1770 STATUS current 1771 DESCRIPTION 1772 "The number of times an outgoing session was not established 1773 on an (D)TLS client because the presented server certificate was 1774 invalid. Reasons for invalidation includes, but is not 1775 limited to, cryptographic validation failures and an unexpected 1776 presented certificate identity." 1777 ::= { tlstmSession 6 } 1779 tlstmTLSProtectionErrors OBJECT-TYPE 1780 SYNTAX Counter32 1781 MAX-ACCESS read-only 1782 STATUS current 1783 DESCRIPTION 1784 "The number of times (D)TLS processing resulted in a message 1785 being discarded because it failed its integrity test, 1786 decryption processing or other (D)TLS processing." 1787 ::= { tlstmSession 7 } 1789 -- Configuration Objects 1790 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1792 -- Certificate mapping 1794 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1796 tlstmCertToSNCount OBJECT-TYPE 1797 SYNTAX Unsigned32 1798 MAX-ACCESS read-only 1799 STATUS current 1800 DESCRIPTION 1801 "A count of the number of entries in the tlstmCertToSNTable" 1802 ::= { tlstmCertificateMapping 1 } 1804 tlstmCertToSNTableLastChanged OBJECT-TYPE 1805 SYNTAX TimeStamp 1806 MAX-ACCESS read-only 1807 STATUS current 1808 DESCRIPTION 1809 "The value of sysUpTime.0 when the tlstmCertToSNTable 1810 was last modified through any means, or 0 if it has not been 1811 modified since the command responder was started." 1812 ::= { tlstmCertificateMapping 2 } 1814 tlstmCertToSNTable OBJECT-TYPE 1815 SYNTAX SEQUENCE OF TlstmCertToSNEntry 1816 MAX-ACCESS not-accessible 1817 STATUS current 1818 DESCRIPTION 1819 "A table listing the X.509 certificates known to the entity 1820 and the associated method for determining the SNMPv3 security 1821 name from a certificate. 1823 On an incoming (D)TLS/SNMP connection the client's presented 1824 certificate must be examined and validated based on an 1825 established trusted path from a CA certificate or self-signed 1826 public certificate (e.g. RFC5280). This table provides a 1827 mapping from a validated certificate to a SNMPv3 securityName. 1828 This table does not provide any mechanisms for uploading 1829 trusted certificates; the transfer of any needed trusted 1830 certificates for path validation is expected to occur through 1831 an out-of-band transfer. 1833 Once the authenticity of a certificate has been verified, this 1834 table is consulted to determine the appropriate securityName 1835 to identify with the remote connection. This is done by 1836 considering each active row from this table in prioritized 1837 order according to its tlstmCertToSNID value. Each row's 1838 tlstmCertToSNFingerprint value determines whether the row is a 1839 match for the incoming connection: 1841 1) If the row's tlstmCertToSNFingerprint value identifies 1842 the presented certificate and the contents of the 1843 presented certificate match a locally cached copy of 1844 the certificate then consider the row as a successful 1845 match. 1847 2) If the row's tlstmCertToSNFingerprint value identifies 1848 a locally held copy of a trusted CA certificate and 1849 that CA certificated was used to validate the path to 1850 the presented certificate then consider the row as a 1851 successful match. 1853 Once a matching row has been found, the tlstmCertToSNMapType 1854 value can be used to determine how the securityName to 1855 associate with the session should be determined. See the 1856 tlstmCertToSNMapType column's DESCRIPTION for details on 1857 determining the securityName value. If it is impossible to 1858 determine a securityName from the row's data combined with the 1859 data presented in the certificate then additional rows MUST be 1860 searched looking for another potential match. If a resulting 1861 securityName mapped from a given row is not compatible with 1862 the needed requirements of a securityName (e.g., VACM imposes 1863 a 32-octet-maximum length and the certificate derived 1864 securityName could be longer) then it must be considered an 1865 invalid match and additional rows MUST be searched looking for 1866 another potential match. 1868 Missing values of tlstmCertToSNID are acceptable and 1869 implementations should continue to the next highest numbered 1870 row. E.G., the table may legally contain only two rows with 1871 tlstmCertToSNID values of 10 and 20. 1873 Users are encouraged to make use of certificates with 1874 subjectAltName fields that can be used as securityNames so 1875 that a single root CA certificate can allow all child 1876 certificate's subjectAltName to map directly to a securityName 1877 via a 1:1 transformation. However, this table is flexible to 1878 allow for situations where existing deployed certificate 1879 infrastructures do not provide adequate subjectAltName values 1880 for use as SNMPv3 securityNames. Certificates may also be 1881 mapped to securityNames using the CommonName portion of the 1882 Subject field but usage of the CommonName field is deprecated. 1883 Direct mapping from each individual certificate fingerprint to 1884 a securityName is also possible but requires one entry in the 1885 table per securityName and requires more management operations 1886 to completely configure a device." 1887 ::= { tlstmCertificateMapping 3 } 1889 tlstmCertToSNEntry OBJECT-TYPE 1890 SYNTAX TlstmCertToSNEntry 1891 MAX-ACCESS not-accessible 1892 STATUS current 1893 DESCRIPTION 1894 "A row in the tlstmCertToSNTable that specifies a mapping for 1895 an incoming (D)TLS certificate to a securityName to use for a 1896 connection." 1897 INDEX { tlstmCertToSNID } 1898 ::= { tlstmCertToSNTable 1 } 1900 TlstmCertToSNEntry ::= SEQUENCE { 1901 tlstmCertToSNID Unsigned32, 1902 tlstmCertToSNFingerprint Fingerprint, 1903 tlstmCertToSNMapType INTEGER, 1904 tlstmCertToSNSecurityName SnmpAdminString, 1905 tlstmCertToSNSANType INTEGER, 1906 tlstmCertToSNStorageType StorageType, 1907 tlstmCertToSNRowStatus RowStatus 1908 } 1910 tlstmCertToSNID OBJECT-TYPE 1911 SYNTAX Unsigned32 1912 MAX-ACCESS not-accessible 1913 STATUS current 1914 DESCRIPTION 1915 "A unique, prioritized index for the given entry." 1916 ::= { tlstmCertToSNEntry 1 } 1918 tlstmCertToSNFingerprint OBJECT-TYPE 1919 SYNTAX Fingerprint 1920 MAX-ACCESS read-create 1921 STATUS current 1922 DESCRIPTION 1923 "A cryptographic hash of a X.509 certificate. The results of 1924 a successful matching fingerprint to either the trusted CA in 1925 the certificate validation path or to the certificate itself 1926 is dictated by the tlstmCertToSNMapType column." 1927 ::= { tlstmCertToSNEntry 2 } 1929 tlstmCertToSNMapType OBJECT-TYPE 1930 SYNTAX INTEGER { specified(1), bySubjectAltName(2), byCN(3) } 1931 MAX-ACCESS read-create 1932 STATUS current 1933 DESCRIPTION 1934 "The mapping type used to obtain the securityName from the 1935 certificate. The possible values of use and their usage 1936 methods are defined as follows: 1938 specified(1): The securityName that should be used to 1939 associate with the session is directly specified 1940 in the tlstmCertToSNecurityName column from this 1941 table. Note: The tlstmCertToSNSecurityName 1942 column's value is ignored for all other 1943 tlstmCertToSNMapType values. 1945 bySubjectAltName(2): 1946 The securityName that should be used to 1947 associate with the session should be taken from 1948 the subjectAltName(s) portion of the client's 1949 X.509 certificate. The subjectAltName used MUST 1950 be the first encountered subjectAltName type 1951 indicated by the tlstmCertToSNSANType column. 1953 If the resulting mapped value from the 1954 subjectAltName component is not compatible with 1955 the needed requirements of a securityName (e.g., 1956 VACM imposes a 32-octet-maximum length and the 1957 certificate derived securityName could be 1958 longer) then the next appropriate subjectAltName 1959 of the correct type should be used if available. 1961 If no appropriate subjectAltName of the given 1962 type is found within the certificate then 1963 additional rows in the tlstmCertToSNTable must 1964 be searched for additional 1965 tlstmCertToSNFingerprint matches. 1967 byCN(3): The securityName that should be used to 1968 associate with the session should be taken from 1969 the CommonName portion of the Subject field from 1970 the client's presented X.509 certificate. 1972 If the value of the CommonName component is not 1973 compatible with the needed requirements of a 1974 securityName (e.g., VACM imposes a 1975 32-octet-maximum length and the certificate 1976 derived securityName could be longer) then 1977 additional rows in the tlstmCertToSNTable must 1978 be searched for additional 1979 tlstmCertToSNFingerprint matches." 1981 DEFVAL { specified } 1982 ::= { tlstmCertToSNEntry 3 } 1984 tlstmCertToSNSecurityName OBJECT-TYPE 1985 SYNTAX SnmpAdminString (SIZE(0..32)) 1986 MAX-ACCESS read-create 1987 STATUS current 1988 DESCRIPTION 1989 "The securityName that the session should use if the 1990 tlstmCertToSNMapType is set to specified(1), otherwise the 1991 value in this column should be ignored. If 1992 tlstmCertToSNMapType is set to specifed(1) and this column 1993 contains a zero-length string (which is not a legal 1994 securityName value) this row is effectively disabled and the 1995 match will not be considered successful and other rows in the 1996 table will need to be searched for a proper match." 1997 DEFVAL { "" } 1998 ::= { tlstmCertToSNEntry 4 } 2000 tlstmCertToSNSANType OBJECT-TYPE 2001 SYNTAX INTEGER { any(1), rfc822Name(2), dNSName(3), 2002 ipAddress(4), otherName(5) } 2003 MAX-ACCESS read-create 2004 STATUS current 2005 DESCRIPTION 2006 "Specifies the subjectAltName type that may be used to extract 2007 the securityName from. 2009 The any(1) value indicates the (D)TLS server should use the 2010 first value found for any of the following subjectAltName 2011 value types for the securityName: rfc822Name, dNSName, and 2012 ipAddress. 2014 When multiple types for a given subjectAltName type are 2015 encountered within a certificate the first legally usable 2016 value is the one selected. 2018 Values for type ipAddress(4) are converted to a valid 2019 securityName by: 2021 1) for IPv4 the value is converted into a decimal dotted 2022 quad address (e.g. '192.0.2.1') 2024 2) for IPv6 addresses the value is converted into a 2025 32-character hexadecimal string without any colon 2026 separators. 2028 Note that the resulting length is the maximum length 2029 supported by the View-Based Access Control Model 2030 (VACM). Note that using both the Transport Security 2031 Model's support for transport prefixes (see the 2032 SNMP-TSM-MIB::snmpTsmConfigurationUsePrefix object for 2033 details) will result in securityName lengths that 2034 exceed what VACM can handle. 2036 Values for type otherName(5) are converted to a valid 2037 securityName by using only the decoded value portion of the 2038 OtherName sequence. I.E. the OBJECT IDENTIFIER portion of the 2039 OtherName sequence is not included as part of the resulting 2040 securityName." 2041 DEFVAL { any } 2042 ::= { tlstmCertToSNEntry 5 } 2044 tlstmCertToSNStorageType OBJECT-TYPE 2045 SYNTAX StorageType 2046 MAX-ACCESS read-create 2047 STATUS current 2048 DESCRIPTION 2049 "The storage type for this conceptual row. Conceptual rows 2050 having the value 'permanent' need not allow write-access to 2051 any columnar objects in the row." 2052 DEFVAL { nonVolatile } 2053 ::= { tlstmCertToSNEntry 6 } 2055 tlstmCertToSNRowStatus OBJECT-TYPE 2056 SYNTAX RowStatus 2057 MAX-ACCESS read-create 2058 STATUS current 2059 DESCRIPTION 2060 "The status of this conceptual row. This object may be used 2061 to create or remove rows from this table. 2063 To create a row in this table, a manager must set this object 2064 to either createAndGo(4) or createAndWait(5). 2066 Until instances of all corresponding columns are appropriately 2067 configured, the value of the corresponding instance of the 2068 tlstmParamsRowStatus column is 'notReady'. 2070 In particular, a newly created row cannot be made active until 2071 the corresponding tlstmCertToSNFingerprint, 2072 tlstmCertToSNMapType, tlstmCertToSNSecurityName, and 2073 tlstmCertToSNSANType columns have been set. 2075 The following objects may not be modified while the 2076 value of this object is active(1): 2078 - tlstmCertToSNFingerprint 2079 - tlstmCertToSNMapType 2080 - tlstmCertToSNSecurityName 2081 - tlstmCertToSNSANType 2082 An attempt to set these objects while the value of 2083 tlstmParamsRowStatus is active(1) will result in 2084 an inconsistentValue error." 2085 ::= { tlstmCertToSNEntry 7 } 2087 -- Maps securityNames to certificates for use by the SNMP-TARGET-MIB 2089 tlstmParamsCount OBJECT-TYPE 2090 SYNTAX Unsigned32 2091 MAX-ACCESS read-only 2092 STATUS current 2093 DESCRIPTION 2094 "A count of the number of entries in the tlstmParamsTable" 2095 ::= { tlstmCertificateMapping 4 } 2097 tlstmParamsTableLastChanged OBJECT-TYPE 2098 SYNTAX TimeStamp 2099 MAX-ACCESS read-only 2100 STATUS current 2101 DESCRIPTION 2102 "The value of sysUpTime.0 when the tlstmParamsTable 2103 was last modified through any means, or 0 if it has not been 2104 modified since the command responder was started." 2105 ::= { tlstmCertificateMapping 5 } 2107 tlstmParamsTable OBJECT-TYPE 2108 SYNTAX SEQUENCE OF TlstmParamsEntry 2109 MAX-ACCESS not-accessible 2110 STATUS current 2111 DESCRIPTION 2112 "This table extends the SNMP-TARGET-MIB's 2113 snmpTargetParamsTable with an additional (D)TLS client-side 2114 certificate fingerprint identifier to use when establishing 2115 new (D)TLS connections." 2116 ::= { tlstmCertificateMapping 6 } 2118 tlstmParamsEntry OBJECT-TYPE 2119 SYNTAX TlstmParamsEntry 2120 MAX-ACCESS not-accessible 2121 STATUS current 2122 DESCRIPTION 2123 "A conceptual row containing a fingerprint hash of a locally 2124 held certificate for a given snmpTargetParamsEntry. The 2125 values in this row should be ignored if the connection that 2126 needs to be established, as indicated by the SNMP-TARGET-MIB 2127 infrastructure, is not a certificate and (D)TLS based 2128 connection. The connection SHOULD NOT be established if the 2129 certificate fingerprint stored in this entry does not point to 2130 a valid locally held certificate or if it points to an usable 2131 certificate (such as might happen when the certificate's 2132 expiration date has been reached)." 2133 INDEX { IMPLIED snmpTargetParamsName } 2134 ::= { tlstmParamsTable 1 } 2136 TlstmParamsEntry ::= SEQUENCE { 2137 tlstmParamsClientFingerprint Fingerprint, 2138 tlstmParamsStorageType StorageType, 2139 tlstmParamsRowStatus RowStatus 2140 } 2142 tlstmParamsClientFingerprint OBJECT-TYPE 2143 SYNTAX Fingerprint 2144 MAX-ACCESS read-create 2145 STATUS current 2146 DESCRIPTION 2147 "A cryptographic hash of a X.509 certificate. This object 2148 should store the hash of a locally held X.509 certificate that 2149 should be used when initiating a (D)TLS connection as a (D)TLS 2150 client." 2151 ::= { tlstmParamsEntry 1 } 2153 tlstmParamsStorageType OBJECT-TYPE 2154 SYNTAX StorageType 2155 MAX-ACCESS read-create 2156 STATUS current 2157 DESCRIPTION 2158 "The storage type for this conceptual row. Conceptual rows 2159 having the value 'permanent' need not allow write-access to 2160 any columnar objects in the row." 2161 DEFVAL { nonVolatile } 2162 ::= { tlstmParamsEntry 2 } 2164 tlstmParamsRowStatus OBJECT-TYPE 2165 SYNTAX RowStatus 2166 MAX-ACCESS read-create 2167 STATUS current 2168 DESCRIPTION 2169 "The status of this conceptual row. This object may be used 2170 to create or remove rows from this table. 2172 To create a row in this table, a manager must set this object 2173 to either createAndGo(4) or createAndWait(5). 2175 Until instances of all corresponding columns are appropriately 2176 configured, the value of the corresponding instance of the 2177 tlstmParamsRowStatus column is 'notReady'. 2179 In particular, a newly created row cannot be made active until 2180 the corresponding tlstmParamsClientFingerprint column has 2181 been set. 2183 The tlstmParamsClientFingerprint object may not be modified 2184 while the value of this object is active(1). 2186 An attempt to set these objects while the value of 2187 tlstmParamsRowStatus is active(1) will result in 2188 an inconsistentValue error. 2190 If this row is deleted it has no effect on the corresponding 2191 row in the targetParamsTable. 2193 If the corresponding row in the targetParamsTable is deleted 2194 then this row must be automatically removed." 2195 ::= { tlstmParamsEntry 3 } 2197 -- Lists expected certificate fingerprints to be presented by a DTLS 2198 -- server 2200 tlstmAddrCount OBJECT-TYPE 2201 SYNTAX Unsigned32 2202 MAX-ACCESS read-only 2203 STATUS current 2204 DESCRIPTION 2205 "A count of the number of entries in the tlstmAddrTable" 2206 ::= { tlstmCertificateMapping 7 } 2208 tlstmAddrTableLastChanged OBJECT-TYPE 2209 SYNTAX TimeStamp 2210 MAX-ACCESS read-only 2211 STATUS current 2212 DESCRIPTION 2213 "The value of sysUpTime.0 when the tlstmAddrTable 2214 was last modified through any means, or 0 if it has not been 2215 modified since the command responder was started." 2216 ::= { tlstmCertificateMapping 8 } 2218 tlstmAddrTable OBJECT-TYPE 2219 SYNTAX SEQUENCE OF TlstmAddrEntry 2220 MAX-ACCESS not-accessible 2221 STATUS current 2222 DESCRIPTION 2223 "This table extends the SNMP-TARGET-MIB's snmpTargetAddrTable 2224 with an expected (D)TLS server-side certificate identifier to 2225 expect when establishing a new (D)TLS connections. If a 2226 matching row in this table exists and the row is active then a 2227 local copy of the certificate matching the fingerprint 2228 identifier should be compared against the certificate being 2229 presented by the server. If the certificate presented by the 2230 server does not match the locally held copy then the 2231 connection MUST NOT be established. If no matching row exists 2232 in this table then the connection SHOULD still proceed if 2233 another certificate validation path algorithm (e.g. RFC5280) 2234 can be followed to a configured trust anchor. " 2235 ::= { tlstmCertificateMapping 9 } 2237 tlstmAddrEntry OBJECT-TYPE 2238 SYNTAX TlstmAddrEntry 2239 MAX-ACCESS not-accessible 2240 STATUS current 2241 DESCRIPTION 2242 "A conceptual row containing a copy of a locally held 2243 certificate's fingerprint for a given snmpTargetAddrEntry. 2244 The values in this row should be ignored if the connection 2245 that needs to be established, as indicated by the 2246 SNMP-TARGET-MIB infrastructure, is not a (D)TLS based 2247 connection. If an tlstmAddrEntry exists for a given 2248 snmpTargetAddrEntry then the presented server certificate MUST 2249 match or the connection MUST NOT be established. If a row in 2250 this table does not exist to match a snmpTargetAddrEntry row 2251 then the connection SHOULD still proceed if some other 2252 certificate validation path algorithm (e.g. RFC5280) can be 2253 followed to a configured trust anchor." 2254 INDEX { IMPLIED snmpTargetAddrName } 2255 ::= { tlstmAddrTable 1 } 2257 TlstmAddrEntry ::= SEQUENCE { 2258 tlstmAddrServerFingerprint Fingerprint, 2259 tlstmAddrStorageType StorageType, 2260 tlstmAddrRowStatus RowStatus 2261 } 2263 tlstmAddrServerFingerprint OBJECT-TYPE 2264 SYNTAX Fingerprint 2265 MAX-ACCESS read-create 2266 STATUS current 2267 DESCRIPTION 2268 "A cryptographic hash of a public X.509 certificate. This 2269 object should store the hash of a local copy of the public 2270 X.509 certificate that the remote server should present during 2271 the (D)TLS connection setup. The presented certificate and 2272 the locally held copy, referred to by this hash value, MUST 2273 match exactly or the connection MUST NOT be established." 2274 ::= { tlstmAddrEntry 1 } 2276 tlstmAddrStorageType OBJECT-TYPE 2277 SYNTAX StorageType 2278 MAX-ACCESS read-create 2279 STATUS current 2280 DESCRIPTION 2281 "The storage type for this conceptual row. Conceptual rows 2282 having the value 'permanent' need not allow write-access to 2283 any columnar objects in the row." 2284 DEFVAL { nonVolatile } 2285 ::= { tlstmAddrEntry 2 } 2287 tlstmAddrRowStatus OBJECT-TYPE 2288 SYNTAX RowStatus 2289 MAX-ACCESS read-create 2290 STATUS current 2291 DESCRIPTION 2292 "The status of this conceptual row. This object may be used 2293 to create or remove rows from this table. 2295 To create a row in this table, a manager must 2296 set this object to either createAndGo(4) or 2297 createAndWait(5). 2299 Until instances of all corresponding columns are 2300 appropriately configured, the value of the 2301 corresponding instance of the tlstmAddrRowStatus 2302 column is 'notReady'. 2304 In particular, a newly created row cannot be made active until 2305 the corresponding tlstmAddrServerFingerprint column has been 2306 set. 2308 The tlstmAddrServerFingerprint object may not be modified 2309 while the value of this object is active(1). 2311 An attempt to set these objects while the value of 2312 tlstmAddrRowStatus is active(1) will result in 2313 an inconsistentValue error. 2315 If this row is deleted it has no effect on the corresponding 2316 row in the targetAddrTable. 2318 If the corresponding row in the targetAddrTable is deleted 2319 then this row must be automatically removed." 2320 ::= { tlstmAddrEntry 3 } 2322 -- ************************************************ 2323 -- tlstmNotifications - Notifications Information 2324 -- ************************************************ 2326 tlstmServerCertNotFound NOTIFICATION-TYPE 2327 STATUS current 2328 DESCRIPTION 2329 "Notification that the server certificate presented by a SNMP 2330 over (D)TLS server could not be found in the tlstmAddrTable." 2331 ::= { tlstmNotifications 1 } 2333 tlstmServerAuthFailure NOTIFICATION-TYPE 2334 OBJECTS { tlstmAddrServerFingerprint } 2335 STATUS current 2336 DESCRIPTION 2337 "Notification that the server certificate presented by an SNMP 2338 over (D)TLS server was found, but the connection could not be 2339 established because of a cryptographic validation failure." 2340 ::= { tlstmNotifications 2 } 2342 -- ************************************************ 2343 -- tlstmCompliances - Conformance Information 2344 -- ************************************************ 2346 tlstmCompliances OBJECT IDENTIFIER ::= { tlstmConformance 1 } 2348 tlstmGroups OBJECT IDENTIFIER ::= { tlstmConformance 2 } 2350 -- ************************************************ 2351 -- Compliance statements 2352 -- ************************************************ 2354 tlstmCompliance MODULE-COMPLIANCE 2355 STATUS current 2356 DESCRIPTION 2357 "The compliance statement for SNMP engines that support the 2358 TLSTM-MIB" 2359 MODULE 2360 MANDATORY-GROUPS { tlstmStatsGroup, 2361 tlstmIncomingGroup, 2362 tlstmOutgoingGroup, 2363 tlstmNotificationGroup } 2364 ::= { tlstmCompliances 1 } 2366 -- ************************************************ 2367 -- Units of conformance 2368 -- ************************************************ 2369 tlstmStatsGroup OBJECT-GROUP 2370 OBJECTS { 2371 tlstmSessionOpens, 2372 tlstmSessionCloses, 2373 tlstmSessionOpenErrors, 2374 tlstmSessionNoAvailableSessions, 2375 tlstmSessionInvalidClientCertificates, 2376 tlstmSessionInvalidServerCertificates, 2377 tlstmTLSProtectionErrors 2378 } 2379 STATUS current 2380 DESCRIPTION 2381 "A collection of objects for maintaining 2382 statistical information of an SNMP engine which 2383 implements the SNMP TLS Transport Model." 2384 ::= { tlstmGroups 1 } 2386 tlstmIncomingGroup OBJECT-GROUP 2387 OBJECTS { 2388 tlstmCertToSNCount, 2389 tlstmCertToSNTableLastChanged, 2390 tlstmCertToSNFingerprint, 2391 tlstmCertToSNMapType, 2392 tlstmCertToSNSecurityName, 2393 tlstmCertToSNSANType, 2394 tlstmCertToSNStorageType, 2395 tlstmCertToSNRowStatus 2396 } 2397 STATUS current 2398 DESCRIPTION 2399 "A collection of objects for maintaining 2400 incoming connection certificate mappings to 2401 securityNames of an SNMP engine which implements the 2402 SNMP TLS Transport Model." 2403 ::= { tlstmGroups 2 } 2405 tlstmOutgoingGroup OBJECT-GROUP 2406 OBJECTS { 2407 tlstmParamsCount, 2408 tlstmParamsTableLastChanged, 2409 tlstmParamsClientFingerprint, 2410 tlstmParamsStorageType, 2411 tlstmParamsRowStatus, 2412 tlstmAddrCount, 2413 tlstmAddrTableLastChanged, 2414 tlstmAddrServerFingerprint, 2415 tlstmAddrStorageType, 2416 tlstmAddrRowStatus 2417 } 2418 STATUS current 2419 DESCRIPTION 2420 "A collection of objects for maintaining 2421 outgoing connection certificates to use when opening 2422 connections as a result of SNMP-TARGET-MIB settings." 2423 ::= { tlstmGroups 3 } 2425 tlstmNotificationGroup NOTIFICATION-GROUP 2426 NOTIFICATIONS { 2427 tlstmServerCertNotFound, 2428 tlstmServerAuthFailure 2429 } 2430 STATUS current 2431 DESCRIPTION 2432 "Notifications" 2433 ::= { tlstmGroups 4 } 2435 END 2437 8. Operational Considerations 2439 This section discusses various operational aspects of deploying 2440 TLSTM. 2442 8.1. Sessions 2444 A session is discussed throughout this document as meaning a security 2445 association between the (D)TLS client and the (D)TLS server. State 2446 information for the sessions are maintained in each TLSTM 2447 implementation and this information is created and destroyed as 2448 sessions are opened and closed. A "broken" session (one side up and 2449 one side down) can result if one side of a session is brought down 2450 abruptly (i.e., reboot, power outage, etc.). Whenever possible, 2451 implementations SHOULD provide graceful session termination through 2452 the use of disconnect messages. Implementations SHOULD also have a 2453 system in place for dealing with "broken" sessions. Implementations 2454 SHOULD support the session resumption feature of TLS. 2456 To simplify session management it is RECOMMENDED that implementations 2457 use separate ports for Notification sessions and for Command 2458 sessions. If this implementation recommendation is followed, (D)TLS 2459 clients will always send REQUEST messages and (D)TLS servers will 2460 always send RESPONSE messages. With this assertion, implementations 2461 may be able to simplify "broken" session handling, session 2462 resumption, and other aspects of session management such as 2463 guaranteeing that Request- Response pairs use the same session. 2465 Implementations SHOULD limit the lifetime of established sessions 2466 depending on the algorithms used for generation of the master session 2467 secret, the privacy and integrity algorithms used to protect 2468 messages, the environment of the session, the amount of data 2469 transferred, and the sensitivity of the data. 2471 8.2. Notification Receiver Credential Selection 2473 When an SNMP engine needs to establish an outgoing session for 2474 notifications, the snmpTargetParamsTable includes an entry for the 2475 snmpTargetParamsSecurityName of the target. However, the receiving 2476 SNMP engine (Server) does not know which (D)TLS certificate to offer 2477 to the Client so that the tmSecurityName identity-authentication will 2478 be successful. 2480 One solution is to maintain a one-to-one mapping between certificates 2481 and incoming ports for notification receivers. This can be handled 2482 at the Notification Originator by configuring the snmpTargetAddrTable 2483 (snmpTargetAddrTDomain and snmpTargetAddrTAddress) and requiring the 2484 receiving SNMP engine to monitor multiple incoming static ports based 2485 on which principals are capable of receiving notifications. 2487 Implementations MAY also choose to designate a single Notification 2488 Receiver Principal to receive all incoming TRAPS and INFORMS or 2489 select an implementation specific method of selecting a server 2490 certificate to present to clients. 2492 8.3. contextEngineID Discovery 2494 Most Command Responders have contextEngineIDs that are identical to 2495 the USM securityEngineID. USM provides a discovery service that 2496 allows Command Generators to determine a securityEngineID and thus a 2497 default contextEngineID to use. Because the TLS Transport Model does 2498 not make use of a securityEngineID, it may be difficult for Command 2499 Generators to discover a suitable default contextEngineID. 2500 Implementations should consider offering another engineID discovery 2501 mechanism to continue providing Command Generators with a suitable 2502 contextEngineID mechanism. A recommended discovery solution is 2503 documented in [RFC5343]. 2505 9. Security Considerations 2507 This document describes a transport model that permits SNMP to 2508 utilize (D)TLS security services. The security threats and how the 2509 (D)TLS transport model mitigates these threats are covered in detail 2510 throughout this document. Security considerations for DTLS are 2511 covered in [RFC4347] and security considerations for TLS are 2512 described in Section 11 and Appendices D, E, and F of TLS 1.2 2513 [RFC5246]. DTLS adds to the security considerations of TLS only 2514 because it is more vulnerable to denial of service attacks. A random 2515 cookie exchange was added to the handshake to prevent anonymous 2516 denial of service attacks. RFC 4347 recommends that the cookie 2517 exchange is utilized for all handshakes and therefore this 2518 specification also RECOMMENDEDs that implementers also support this 2519 cookie exchange. 2521 9.1. Certificates, Authentication, and Authorization 2523 Implementations are responsible for providing a security certificate 2524 installation and configuration mechanism. Implementations SHOULD 2525 support certificate revocation lists. 2527 (D)TLS provides for authentication of the identity of both the (D)TLS 2528 server and the (D)TLS client. Access to MIB objects for the 2529 authenticated principal MUST be enforced by an access control 2530 subsystem (e.g. the VACM). 2532 Authentication of the Command Generator principal's identity is 2533 important for use with the SNMP access control subsystem to ensure 2534 that only authorized principals have access to potentially sensitive 2535 data. The authenticated identity of the Command Generator 2536 principal's certificate is mapped to an SNMP model-independent 2537 securityName for use with SNMP access control. 2539 The (D)TLS handshake only provides assurance that the certificate of 2540 the authenticated identity has been signed by an configured accepted 2541 Certificate Authority. (D)TLS has no way to further authorize or 2542 reject access based on the authenticated identity. An Access Control 2543 Model (such as the VACM) provides access control and authorization of 2544 a Command Generator's requests to a Command Responder and a 2545 Notification Responder's authorization to receive Notifications from 2546 a Notification Originator. However to avoid man-in-the-middle 2547 attacks both ends of the (D)TLS based connection MUST check the 2548 certificate presented by the other side against what was expected. 2549 For example, Command Generators must check that the Command Responder 2550 presented and authenticated itself with a X.509 certificate that was 2551 expected. Not doing so would allow an impostor, at a minimum, to 2552 present false data, receive sensitive information and/or provide a 2553 false belief that configuration was actually received and acted upon. 2554 Authenticating and verifying the identity of the (D)TLS server and 2555 the (D)TLS client for all operations ensures the authenticity of the 2556 SNMP engine that provides MIB data. 2558 The instructions found in the DESCRIPTION clause of the 2559 tlstmCertToSNTable object must be followed exactly. It is also 2560 important that the rows of the table be searched in prioritized order 2561 starting with the row containing the lowest numbered tlstmCertToSNID 2562 value. 2564 9.2. Use with SNMPv1/SNMPv2c Messages 2566 The SNMPv1 and SNMPv2c message processing described in RFC3484 (BCP 2567 74) [RFC3584] always selects the SNMPv1(1) Security Model for an 2568 SNMPv1 message, or the SNMPv2c(2) Security Model for an SNMPv2c 2569 message. When running SNMPv1/SNMPv2c over a secure transport like 2570 the TLS Transport Model, the securityName and securityLevel used for 2571 access control decisions are then derived from the community string, 2572 not the authenticated identity and securityLevel provided by the TLS 2573 Transport Model. 2575 9.3. MIB Module Security 2577 There are a number of management objects defined in this MIB module 2578 with a MAX-ACCESS clause of read-write and/or read-create. Such 2579 objects may be considered sensitive or vulnerable in some network 2580 environments. The support for SET operations in a non-secure 2581 environment without proper protection can have a negative effect on 2582 network operations. These are the tables and objects and their 2583 sensitivity/vulnerability: 2585 o The tlstmParamsTable can be used to change the outgoing X.509 2586 certificate used to establish a (D)TLS connection. Modification 2587 to objects in this table need to be adequately authenticated since 2588 modification to values in this table will have profound impacts to 2589 the security of outbound connections from the device. Since 2590 knowledge of authorization rules and certificate usage mechanisms 2591 may be considered sensitive, protection from disclosure of the 2592 SNMP traffic via encryption is also highly recommended. 2594 o The tlstmAddrTable can be used to change the expectations of the 2595 certificates presented by a remote (D)TLS server. Modification to 2596 objects in this table need to be adequately authenticated since 2597 modification to values in this table will have profound impacts to 2598 the security of outbound connections from the device. Since 2599 knowledge of authorization rules and certificate usage mechanisms 2600 may be considered sensitive, protection from disclosure of the 2601 SNMP traffic via encryption is also highly recommended. 2603 o The tlstmCertToSNTable is used to specify the mapping of incoming 2604 X.509 certificates to SNMPv3 securityNames. Modification to 2605 objects in this table need to be adequately authenticated since 2606 modification to values in this table will have profound impacts to 2607 the security of incoming connections to the device. Since 2608 knowledge of authorization rules and certificate usage mechanisms 2609 may be considered sensitive, protection from disclosure of the 2610 SNMP traffic via encryption is also highly recommended. 2612 Some of the readable objects in this MIB module (i.e., objects with a 2613 MAX-ACCESS other than not-accessible) may be considered sensitive or 2614 vulnerable in some network environments. It is thus important to 2615 control even GET and/or NOTIFY access to these objects and possibly 2616 to even encrypt the values of these objects when sending them over 2617 the network via SNMP. These are the tables and objects and their 2618 sensitivity/vulnerability: 2620 o This MIB contains a collection of counters that monitor the (D)TLS 2621 connections being established with a device. Since knowledge of 2622 connection and certificate usage mechanisms may be considered 2623 sensitive, protection from disclosure of the SNMP traffic via 2624 encryption is also highly recommended. 2626 SNMP versions prior to SNMPv3 did not include adequate security. 2627 Even if the network itself is secure (for example by using IPsec), 2628 even then, there is no control as to who on the secure network is 2629 allowed to access and GET/SET (read/change/create/delete) the objects 2630 in this MIB module. 2632 It is RECOMMENDED that implementers consider the security features as 2633 provided by the SNMPv3 framework (see [RFC3410], section 8), 2634 including full support for the SNMPv3 cryptographic mechanisms (for 2635 authentication and privacy). 2637 Further, deployment of SNMP versions prior to SNMPv3 is NOT 2638 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 2639 enable cryptographic security. It is then a customer/operator 2640 responsibility to ensure that the SNMP entity giving access to an 2641 instance of this MIB module is properly configured to give access to 2642 the objects only to those principals (users) that have legitimate 2643 rights to indeed GET or SET (change/create/delete) them. 2645 10. IANA Considerations 2647 IANA is requested to assign: 2649 1. a TCP port number in the range 1..1023 in the 2650 http://www.iana.org/assignments/port-numbers registry which will 2651 be the default port for receipt of SNMP command messages over a 2652 TLS Transport Model as defined in this document, 2654 2. a TCP port number in the range 1..1023 in the 2655 http://www.iana.org/assignments/port-numbers registry which will 2656 be the default port for receipt of SNMP notification messages 2657 over a TLS Transport Model as defined in this document, 2659 3. a UDP port number in the range 1..1023 in the 2660 http://www.iana.org/assignments/port-numbers registry which will 2661 be the default port for receipt of SNMP command messages over a 2662 DTLS/UDP connection as defined in this document, 2664 4. a UDP port number in the range 1..1023 in the 2665 http://www.iana.org/assignments/port-numbers registry which will 2666 be the default port for receipt of SNMP notification messages 2667 over a DTLS/UDP connection as defined in this document, 2669 5. a SCTP port number in the range 1..1023 in the 2670 http://www.iana.org/assignments/port-numbers registry which will 2671 be the default port for receipt of SNMP command messages over a 2672 DTLS/SCTP connection as defined in this document, 2674 6. a SCTP port number in the range 1..1023 in the 2675 http://www.iana.org/assignments/port-numbers registry which will 2676 be the default port for receipt of SNMP notification messages 2677 over a DTLS/SCTP connection as defined in this document, 2679 7. an SMI number under snmpDomains for the snmpTLSDomain object 2680 identifier, 2682 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2683 identifier, 2685 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2686 object identifier, 2688 10. a SMI number under snmpModules, for the MIB module in this 2689 document, 2691 11. "tls" as the corresponding prefix for the snmpTLSDomain in the 2692 SNMP Transport Model registry, 2694 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2695 the SNMP Transport Model registry, 2697 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2698 the SNMP Transport Model registry; 2700 If possible, IANA is requested to use matching port numbers for all 2701 assignments for SNMP Commands being sent over TLS, DTLS/UDP, DTLS/ 2702 SCTP. 2704 If possible, IANA is requested to use matching port numbers for all 2705 assignments for SNMP Notifications being sent over TLS, DTLS/UDP, 2706 DTLS/SCTP. 2708 Editor's note: this section should be replaced with appropriate 2709 descriptive assignment text after IANA assignments are made and prior 2710 to publication. 2712 11. Acknowledgements 2714 This document closely follows and copies the Secure Shell Transport 2715 Model for SNMP defined by David Harrington and Joseph Salowey in 2716 [RFC5292]. 2718 This document was reviewed by the following people who helped provide 2719 useful comments (in alphabetical order): Andy Donati, Pasi Eronen, 2720 David Harrington, Jeffrey Hutzelman, Alan Luchuk, Randy Presuhn, Ray 2721 Purvis, Joseph Salowey, Jurgen Schonwalder, Dave Shield. 2723 This work was supported in part by the United States Department of 2724 Defense. Large portions of this document are based on work by 2725 General Dynamics C4 Systems and the following individuals: Brian 2726 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2727 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2728 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2730 12. References 2732 12.1. Normative References 2734 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2735 Requirement Levels", BCP 14, RFC 2119, March 1997. 2737 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2738 Schoenwaelder, Ed., "Structure of Management Information 2739 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2741 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2742 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2743 STD 58, RFC 2579, April 1999. 2745 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2746 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2747 April 1999. 2749 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2750 Architecture for Describing Simple Network Management 2751 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2752 December 2002. 2754 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2755 Management Protocol (SNMP) Applications", STD 62, 2756 RFC 3413, December 2002. 2758 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2759 (USM) for version 3 of the Simple Network Management 2760 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2762 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2763 Access Control Model (VACM) for the Simple Network 2764 Management Protocol (SNMP)", STD 62, RFC 3415, 2765 December 2002. 2767 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2768 Simple Network Management Protocol (SNMP)", STD 62, 2769 RFC 3418, December 2002. 2771 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2772 "Coexistence between Version 1, Version 2, and Version 3 2773 of the Internet-standard Network Management Framework", 2774 BCP 74, RFC 3584, August 2003. 2776 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2777 Security", RFC 4347, April 2006. 2779 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2780 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2782 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2783 Housley, R., and W. Polk, "Internet X.509 Public Key 2784 Infrastructure Certificate and Certificate Revocation List 2785 (CRL) Profile", RFC 5280, May 2008. 2787 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 2788 for the Simple Network Management Protocol (SNMP)", 2789 RFC 5590, June 2009. 2791 [RFC5591] Harrington, D. and W. Hardaker, "Transport Security Model 2792 for the Simple Network Management Protocol (SNMP)", 2793 RFC 5591, June 2009. 2795 12.2. Informative References 2797 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2798 Protocol", RFC 2522, March 1999. 2800 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2801 "Introduction and Applicability Statements for Internet- 2802 Standard Management Framework", RFC 3410, December 2002. 2804 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2805 RFC 4306, December 2005. 2807 [RFC5292] Chen, E. and S. Sangli, "Address-Prefix-Based Outbound 2808 Route Filter for BGP-4", RFC 5292, August 2008. 2810 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2811 (SNMP) Context EngineID Discovery", RFC 5343, 2812 September 2008. 2814 [I-D.saintandre-tls-server-id-check] 2815 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2816 "Best Practices for Checking of Server Identities in the 2817 Context of Transport Layer Security (TLS)". 2819 [AES] National Institute of Standards, "Specification for the 2820 Advanced Encryption Standard (AES)". 2822 [DES] National Institute of Standards, "American National 2823 Standard for Information Systems-Data Link Encryption". 2825 [DSS] National Institute of Standards, "Digital Signature 2826 Standard". 2828 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2829 Obtaining Digital Signatures and Public-Key 2830 Cryptosystems". 2832 [x509] Rivest, R., Shamir, A., and L. M. Adleman, "A Method for 2833 Obtaining Digital Signatures and Public-Key 2834 Cryptosystems". 2836 Appendix A. (D)TLS Overview 2838 The (D)TLS protocol is composed of two layers: the (D)TLS Record 2839 Protocol and the (D)TLS Handshake Protocol. The following 2840 subsections provide an overview of these two layers. Please refer to 2841 [RFC4347] for a complete description of the protocol. 2843 A.1. The (D)TLS Record Protocol 2845 At the lowest layer, layered on top of the transport control protocol 2846 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 2847 Record Protocol. 2849 The (D)TLS Record Protocol provides security that has three basic 2850 properties: 2852 o The session can be confidential. Symmetric cryptography is used 2853 for data encryption (e.g., [AES], [DES] etc.). The keys for this 2854 symmetric encryption are generated uniquely for each session and 2855 are based on a secret negotiated by another protocol (such as the 2856 (D)TLS Handshake Protocol). The Record Protocol can also be used 2857 without encryption. 2859 o Messages can have data integrity. Message transport includes a 2860 message integrity check using a keyed MAC. Secure hash functions 2861 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 2862 Protocol can operate without a MAC, but is generally only used in 2863 this mode while another protocol is using the Record Protocol as a 2864 transport for negotiating security parameters. 2866 o Messages are protected against replay. (D)TLS uses explicit 2867 sequence numbers and integrity checks. DTLS uses a sliding window 2868 to protect against replay of messages within a session. 2870 (D)TLS also provides protection against replay of entire sessions. 2871 In a properly-implemented keying material exchange, both sides will 2872 generate new random numbers for each exchange. This results in 2873 different encryption and integrity keys for every session. 2875 A.2. The (D)TLS Handshake Protocol 2877 The (D)TLS Record Protocol is used for encapsulation of various 2878 higher-level protocols. One such encapsulated protocol, the (D)TLS 2879 Handshake Protocol, allows the server and client to authenticate each 2880 other and to negotiate an integrity algorithm, an encryption 2881 algorithm and cryptographic keys before the application protocol 2882 transmits or receives its first octet of data. Only the (D)TLS 2883 client can initiate the handshake protocol. The (D)TLS Handshake 2884 Protocol provides security that has four basic properties: 2886 o The peer's identity can be authenticated using asymmetric (public 2887 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 2888 authentication can be made optional, but is generally required by 2889 at least one of the peers. 2891 (D)TLS supports three authentication modes: authentication of both 2892 the server and the client, server authentication with an 2893 unauthenticated client, and total anonymity. For authentication 2894 of both entities, each entity provides a valid certificate chain 2895 leading to an acceptable certificate authority. Each entity is 2896 responsible for verifying that the other's certificate is valid 2897 and has not expired or been revoked. See 2898 [I-D.saintandre-tls-server-id-check] for further details on 2899 standardized processing when checking server certificate 2900 identities. 2902 o The negotiation of a shared secret is secure: the negotiated 2903 secret is unavailable to eavesdroppers, and for any authenticated 2904 handshake the secret cannot be obtained, even by an attacker who 2905 can place himself in the middle of the session. 2907 o The negotiation is not vulnerable to malicious modification: it is 2908 infeasible for an attacker to modify negotiation communication 2909 without being detected by the parties to the communication. 2911 o DTLS uses a stateless cookie exchange to protect against anonymous 2912 denial of service attacks and has retransmission timers, sequence 2913 numbers, and counters to handle message loss, reordering, and 2914 fragmentation. 2916 Appendix B. PKIX Certificate Infrastructure 2918 Users of a public key from a PKIX / X.509 certificate can be be 2919 confident that the associated private key is owned by the correct 2920 remote subject (person or system) with which an encryption or digital 2921 signature mechanism will be used. This confidence is obtained 2922 through the use of public key certificates, which are data structures 2923 that bind public key values to subjects. The binding is asserted by 2924 having a trusted CA digitally sign each certificate. The CA may base 2925 this assertion upon technical means (i.e., proof of possession 2926 through a challenge- response protocol), presentation of the private 2927 key, or on an assertion by the subject. A certificate has a limited 2928 valid lifetime which is indicated in its signed contents. Because a 2929 certificate's signature and timeliness can be independently checked 2930 by a certificate-using client, certificates can be distributed via 2931 untrusted communications and server systems, and can be cached in 2932 unsecured storage in certificate-using systems. 2934 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8, which was 2935 first published in 1988 as part of the X.500 Directory 2936 recommendations, defines a standard certificate format [x509] which 2937 is a certificate which binds a subject (principal) to a public key 2938 value. This was later further documented in [RFC5280]. 2940 A X.509 certificate is a sequence of three required fields: 2942 tbsCertificate: The tbsCertificate field contains the names of the 2943 subject and issuer, a public key associated with the subject, a 2944 validity period, and other associated information. This field may 2945 also contain extension components. 2947 signatureAlgorithm: The signatureAlgorithm field contains the 2948 identifier for the cryptographic algorithm used by the certificate 2949 authority (CA) to sign this certificate. 2951 signatureValue: The signatureValue field contains a digital 2952 signature computed by the CA upon the ASN.1 DER encoded 2953 tbsCertificate field. The ASN.1 DER encoded tbsCertificate is 2954 used as the input to the signature function. This signature value 2955 is then ASN.1 DER encoded as a BIT STRING and included in the 2956 Certificate's signature field. By generating this signature, the 2957 CA certifies the validity of the information in the tbsCertificate 2958 field. In particular, the CA certifies the binding between the 2959 public key material and the subject of the certificate. 2961 The basic X.509 authentication procedure is as follows: A system is 2962 initialized with a number of root certificates that contain the 2963 public keys of a number of trusted CAs. When a system receives a 2964 X.509 certificate, signed by one of those CAs, the certificate has to 2965 be verified. It first checks the signatureValue field by using the 2966 public key of the corresponding trusted CA. Then it compares the 2967 decrypted information with a digest of the tbsCertificate field. If 2968 they match, then the subject in the tbsCertificate field is 2969 authenticated. 2971 Appendix C. Target and Notificaton Configuration Example 2973 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2974 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2975 daunting task without an example to follow. The following section 2976 describes an example of what pieces must be in place to accomplish 2977 this configuration. 2979 The isAccessAllowed() ASI requires configuration to exist in the 2980 following SNMP-VIEW-BASED-ACM-MIB tables: 2982 vacmSecurityToGroupTable 2983 vacmAccessTable 2984 vacmViewTreeFamilyTable 2986 The only table that needs to be discussed as particularly different 2987 here is the vacmSecurityToGroupTable. This table is indexed by both 2988 the SNMPv3 security model and the security name. The security model, 2989 when TLSTM is in use, should be set to the value of 4, corresponding 2990 to the TSM [RFC5591]. An example vacmSecurityToGroupTable row might 2991 be filled out as follows (using a single SNMP SET request): 2993 vacmSecurityModel = 4 (TSM) 2994 vacmSecurityName = "blueberry" 2995 vacmGroupName = "administrators" 2996 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2997 vacmSecurityToGroupStatus = 4 (createAndGo) 2999 This example will assume that the "administrators" group has been 3000 given proper permissions via rows in the vacmAccessTable and 3001 vacmViewTreeFamilyTable. 3003 Depending on whether this VACM configuration is for a Command 3004 Responder or a Command Generator the security name "blueberry" will 3005 come from a few different locations. 3007 C.1. Configuring the Notification Generator 3009 For Notification Generator's performing authorization checks, the 3010 server's certificate must be verified against the expected 3011 certificate before proceeding to send the notification. The expected 3012 certificate from the server may be listed in the tlstmAddrTable or 3013 may be determined through other X.509 path validation mechanisms. 3014 The securityName to use for VACM authorization checks is set by the 3015 SNMP-TARGET-MIB's snmpTargetParamsSecurityName column. 3017 The certificate that the notification generator should present to the 3018 server is taken from the tlstmParamsClientFingerprint column from the 3019 appropriate entry in the tlstmParamsTable table. 3021 C.2. Configuring the Command Responder 3023 For Command Responder applications, the vacmSecurityName "blueberry" 3024 value is a value that needs derive from an incoming (D)TLS session. 3025 The mapping from a recevied (D)TLS client certificate to a 3026 securityName is done with the tlstmCertToSNTable. The certificates 3027 must be loaded into the device so that a tlstmCertToSNEntry may refer 3028 to it. As an example, consider the following entry which will 3029 provide a mapping from a client's public X.509's hash fingerprint 3030 directly to the "blueberry" securityName: 3032 tlstmCertToSNID = 1 (chosen by ordering preference) 3033 tlstmCertToSNFingerprint = HASH (appropriate fingerprint) 3034 tlstmCertToSNMapType = 1 (specified) 3035 tlstmCertToSNSecurityName = "blueberry" 3036 tlstmCertToSNStorageType = 3 (nonVolatile) 3037 tlstmCertToSNRowStatus = 4 (createAndGo) 3039 The above is an example of how to map a particular certificate to a 3040 particular securityName. It is recommended, however, that users make 3041 use of direct subjectAltName or CommonName mappings where possible as 3042 it provides a more scalable approach to certificate management. This 3043 entry provides an example of using a subjectAltName mapping: 3045 tlstmCertToSNID = 1 (chosen by ordering preference) 3046 tlstmCertToSNFingerprint = HASH (appropriate fingerprint) 3047 tlstmCertToSNMapType = 2 (bySubjectAltName) 3048 tlstmCertToSNSANType = 1 (any) 3049 tlstmCertToSNStorageType = 3 (nonVolatile) 3050 tlstmCertToSNRowStatus = 4 (createAndGo) 3052 The above entry indicates the subjectAltName field for certificates 3053 created by an Issuing certificate with a corresponding fingerprint 3054 will be trusted to always produce common names that are directly 1 to 3055 1 mappable into SNMPv3 securityNames. This type of configuration 3056 should only be used when the certificate authorities naming 3057 conventions are carefully controlled. 3059 In the example, if the incoming (D)TLS client provided certificate 3060 contained a subjectAltName where the first listed subjectAltName in 3061 the extension is the rfc822Name of "blueberry", the certificate was 3062 signed by a certificate matching the tlstmCertToSNFingerprint value 3063 and the CA's certificate was properly installed on the device then 3064 the string "blueberry" would be used as the securityName for the 3065 session. 3067 Author's Address 3069 Wes Hardaker 3070 Sparta, Inc. 3071 P.O. Box 382 3072 Davis, CA 95617 3073 USA 3075 Phone: +1 530 792 1913 3076 Email: ietf@hardakers.net