idnits 2.17.00 (12 Aug 2021) /tmp/idnits36194/draft-ietf-isms-dtls-tm-00.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 366 has weird spacing: '...patcher v ...' == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 1, 2009) is 4644 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) == Outdated reference: draft-ietf-isms-transport-security-model has been published as RFC 5591 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-isms-transport-security-model' == Outdated reference: draft-ietf-isms-tmsm has been published as RFC 5590 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-isms-tmsm' -- Obsolete informational reference (is this intentional?): RFC 4306 (Obsoleted by RFC 5996) == Outdated reference: draft-ietf-isms-secshell has been published as RFC 5592 == Outdated reference: draft-saintandre-tls-server-id-check has been published as RFC 6125 Summary: 3 errors (**), 0 flaws (~~), 8 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ISMS W. Hardaker 3 Internet-Draft Sparta, Inc. 4 Intended status: Standards Track September 1, 2009 5 Expires: March 5, 2010 7 Transport Layer Security Transport Model for SNMP 8 draft-ietf-isms-dtls-tm-00.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 March 5, 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 . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . 20 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.5. Relationship to Other MIB Modules . . . . . . . . . . . . 30 115 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 30 116 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 30 117 8. Operational Considerations . . . . . . . . . . . . . . . . . . 53 118 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 53 119 8.2. Notification Receiver Credential Selection . . . . . . . . 53 120 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 54 121 9. Security Considerations . . . . . . . . . . . . . . . . . . . 54 122 9.1. Certificates, Authentication, and Authorization . . . . . 54 123 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 55 124 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 56 125 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 126 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 58 127 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 128 12.1. Normative References . . . . . . . . . . . . . . . . . . . 59 129 12.2. Informative References . . . . . . . . . . . . . . . . . . 60 130 Appendix A. (D)TLS Overview . . . . . . . . . . . . . . . . . . . 61 131 A.1. The (D)TLS Record Protocol . . . . . . . . . . . . . . . . 61 132 A.2. The (D)TLS Handshake Protocol . . . . . . . . . . . . . . 62 133 Appendix B. PKIX Certificate Infrastructure . . . . . . . . . . . 63 134 Appendix C. Target and Notificaton Configuration Example . . . . 64 135 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 66 137 1. Introduction 139 It is important to understand the modular SNMPv3 architecture as 140 defined by [RFC3411] and enhanced by the Transport Subsystem 141 [I-D.ietf-isms-tmsm]. It is also important to understand the 142 terminology of the SNMPv3 architecture in order to understand where 143 the Transport Model described in this document fits into the 144 architecture and how it interacts with the other architecture 145 subsystems. For a detailed overview of the documents that describe 146 the current Internet-Standard Management Framework, please refer to 147 Section 7 of [RFC3410]. 149 This document describes a Transport Model that makes use of the 150 Transport Layer Security (TLS) [RFC5246] and the Datagram Transport 151 Layer Security (DTLS) Protocol [RFC4347], within a transport 152 subsystem [I-D.ietf-isms-tmsm]. DTLS is the datagram variant of the 153 Transport Layer Security (TLS) protocol [RFC5246]. The Transport 154 Model in this document is referred to as the Transport Layer Security 155 Transport Model (TLSTM). TLS and DTLS take advantage of the X.509 156 public keying infrastructure [RFC5280]. This transport model is 157 designed to meet the security and operational needs of network 158 administrators, operate in both environments where a connectionless 159 (e.g. UDP or SCTP) transport is preferred and in environments where 160 large quantities of data need to be sent (e.g. over a TCP based 161 stream). Both TLS and DTLS integrate well into existing public 162 keying infrastructures. 164 This document also defines a portion of the Management Information 165 Base (MIB) for use with network management protocols. In particular 166 it defines objects for managing the TLS Transport Model for SNMP. 168 For a detailed overview of the documents that describe the current 169 Internet-Standard Management Framework, please refer to section 7 of 170 RFC [RFC3410]. 172 Managed objects are accessed via a virtual information store, termed 173 the Management Information Base or MIB. MIB objects are generally 174 accessed through the Simple Network Management Protocol (SNMP). 175 Objects in the MIB are defined using the mechanisms defined in the 176 Structure of Management Information (SMI). This memo specifies a MIB 177 module that is compliant to the SMIv2, which is described in STD 58, 178 [RFC2578] , STD 58, [RFC2579] and STD 58, [RFC2580] 180 The diagram shown below gives a conceptual overview of two SNMP 181 entities communicating using the TLS Transport Model. One entity 182 contains a Command Responder and Notification Originator application, 183 and the other a Command Generator and Notification Responder 184 application. It should be understood that this particular mix of 185 application types is an example only and other combinations are 186 equally as legitimate. 188 +----------------------------------------------------------------+ 189 | Network | 190 +----------------------------------------------------------------+ 191 ^ ^ ^ ^ 192 |Notifications |Commands |Commands |Notifications 193 +---|---------------------|--------+ +--|---------------|-------------+ 194 | V V | | V V | 195 | +------------+ +------------+ | | +-----------+ +----------+ | 196 | | (D)TLS | | (D)TLS | | | | (D)TLS | | (D)TLS | | 197 | | Service | | Service | | | | Service | | Service | | 198 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 199 | +------------+ +------------+ | | +-----------+ +----------+ | 200 | ^ ^ | | ^ ^ | 201 | | | | | | | | 202 | +--+----------+ | | +-+--------------+ | 203 | +-----|---------+----+ | | +---|--------+----+ | 204 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 205 | | +------+ +----+ | | | | | +------+ +----+ | | | 206 | | | DTLS | <---------->| Cache | | | | | DTLS | <---->| Cache | | 207 | | | TM | | | | | | | | TM | | | | | 208 | | +------+ | +-------+ | | | +------+ | +--------+ | 209 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 210 | +--------------------+ | | | +-----------------+ | | 211 | ^ +----+ | | ^ | | 212 | | | | | | | | 213 | v | | | V | | 214 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 215 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 216 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 217 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 218 | | | | | | | | | | | | | | | | | | 219 | | | | | |+---+| | | | | | | | |+---+| | | 220 | | | | +-----+ | || || | | | | | |+----+| || || | | 221 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 222 | | | | +-----+ | || || | | | | |+----+| || || | 223 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 224 | ^ | | | | | | ^ | | | | | 225 | | +----------+ +-----+ | | | +------+ +-----+ | 226 | +-+------------+ | | +-+------------+ | 227 | ^ ^ | | ^ ^ | 228 | | | | | | | | 229 | v v | | V V | 230 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 231 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 232 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RESPONDER | | 233 | | application | | applications | | | |application| | application | | 234 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 235 | SNMP entity | | SNMP entity | 236 +----------------------------------+ +--------------------------------+ 238 1.1. Conventions 240 For consistency with SNMP-related specifications, this document 241 favors terminology as defined in STD62 rather than favoring 242 terminology that is consistent with non-SNMP specifications. This is 243 consistent with the IESG decision to not require the SNMPv3 244 terminology be modified to match the usage of other non-SNMP 245 specifications when SNMPv3 was advanced to Full Standard. 247 Authentication in this document typically refers to the English 248 meaning of "serving to prove the authenticity of" the message, not 249 data source authentication or peer identity authentication. 251 Large portions of this document simultaneously refer to both TLS and 252 DTLS when discussing TLSTM components that function equally with 253 either protocol. "(D)TLS" is used in these places to indicate that 254 the statement applies to either or both protocols as appropriate. 255 When a distinction between the protocols is needed they are referred 256 to independently through the use of "TLS" or "DTLS". The Transport 257 Model, however, is named "TLS Transport Model" and refers not to the 258 TLS or DTLS protocol but to the standard defined in this document, 259 which includes support for both TLS and DTLS. 261 The terms "manager" and "agent" are not used in this document, 262 because in the RFC 3411 architecture [RFC3411], all SNMP entities 263 have the capability of acting in either manager or agent or in both 264 roles depending on the SNMP application types supported in the 265 implementation. Where distinction is required, the application names 266 of Command Generator, Command Responder, Notification Originator, 267 Notification Receiver, and Proxy Forwarder are used. See "SNMP 268 Applications" [RFC3413] for further information. 270 Throughout this document, the terms "client" and "server" are used to 271 refer to the two ends of the (D)TLS transport connection. The client 272 actively opens the (D)TLS connection, and the server passively 273 listens for the incoming (D)TLS connection. Either SNMP entity may 274 act as client or as server, as discussed further below. 276 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 277 implement Security Model in STD 62. While (D)TLS and USM frequently 278 refer to a user, the terminology preferred in RFC3411 [RFC3411] and 279 in this memo is "principal". A principal is the "who" on whose 280 behalf services are provided or processing takes place. A principal 281 can be, among other things, an individual acting in a particular 282 role; a set of individuals, with each acting in a particular role; an 283 application or a set of applications, or a combination of these 284 within an administrative domain. 286 Throughout this document, the term "session" is used to refer to a 287 secure association between two TLS Transport Models that permits the 288 transmission of one or more SNMP messages within the lifetime of the 289 session. 291 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 292 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 293 document are to be interpreted as described in [RFC2119]. 295 2. The Transport Layer Security Protocol 297 (D)TLS provides authentication, data message integrity, and privacy 298 at the transport layer. (See [RFC4347]) 300 The primary goals of the TLS Transport Model are to provide privacy, 301 source authentication and data integrity between two communicating 302 SNMP entities. The TLS and DTLS protocols provide a secure transport 303 upon which the TLSTM is based. An overview of (D)TLS can be found in 304 section Appendix A. Please refer to [RFC4347] for a complete 305 description of the protocol. 307 2.1. SNMP requirements of (D)TLS 309 To properly support the SNMP over TLS Transport Model, the (D)TLS 310 implementation requires the following: 312 o The TLS Transport Model SHOULD always use authentication of both 313 the server and the client. 315 o At a minimum the TLS Transport Model MUST support authentication 316 of the Command Generator principals to guarantee the authenticity 317 of the securityName. 319 o The TLS Transport Model SHOULD support the message encryption to 320 protect sensitive data from eavesdropping attacks. 322 3. How the TLSTM fits into the Transport Subsystem 324 A transport model is a component of the Transport Subsystem. The TLS 325 Transport Model thus fits between the underlying (D)TLS transport 326 layer and the message dispatcher [RFC3411] component of the SNMP 327 engine and the Transport Subsystem. 329 The TLS Transport Model will establish a session between itself and 330 the TLS Transport Model of another SNMP engine. The sending 331 transport model passes unprotected messages from the dispatcher to 332 (D)TLS to be protected, and the receiving transport model accepts 333 decrypted and authenticated/integrity-checked incoming messages from 334 (D)TLS and passes them to the dispatcher. 336 After a TLS Transport Model session is established, SNMP messages can 337 conceptually be sent through the session from one SNMP message 338 dispatcher to another SNMP message dispatcher. If multiple SNMP 339 messages are needed to be passed between two SNMP applications they 340 SHOULD be passed through the same session. A TLSTM implementation 341 engine MAY choose to close a (D)TLS session to conserve resources. 343 The TLS Transport Model of an SNMP engine will perform the 344 translation between (D)TLS-specific security parameters and SNMP- 345 specific, model-independent parameters. 347 The diagram below depicts where the TLS Transport Model fits into the 348 architecture described in RFC3411 and the Transport Subsystem: 350 +------------------------------+ 351 | Network | 352 +------------------------------+ 353 ^ ^ ^ 354 | | | 355 v v v 356 +-------------------------------------------------------------------+ 357 | +--------------------------------------------------+ | 358 | | Transport Subsystem | +--------+ | 359 | | +-----+ +-----+ +-------+ +-------+ | | | | 360 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 361 | | | | | TM | | TM | | | | | | | 362 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 363 | +--------------------------------------------------+ ^ | 364 | ^ | | 365 | | | | 366 | Dispatcher v | | 367 | +--------------+ +---------------------+ +----------------+ | | 368 | | Transport | | Message Processing | | Security | | | 369 | | Dispatch | | Subsystem | | Subsystem | | | 370 | | | | +------------+ | | +------------+ | | | 371 | | | | +->| v1MP |<--->| | USM | | | | 372 | | | | | +------------+ | | +------------+ | | | 373 | | | | | +------------+ | | +------------+ | | | 374 | | | | +->| v2cMP |<--->| | Transport | | | | 375 | | Message | | | +------------+ | | | Security |<--+ | 376 | | Dispatch <---->| +------------+ | | | Model | | | 377 | | | | +->| v3MP |<--->| +------------+ | | 378 | | | | | +------------+ | | +------------+ | | 379 | | PDU Dispatch | | | +------------+ | | | Other | | | 380 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 381 | ^ | +------------+ | | +------------+ | | 382 | | +---------------------+ +----------------+ | 383 | v | 384 | +-------+-------------------------+---------------+ | 385 | ^ ^ ^ | 386 | | | | | 387 | v v v | 388 | +-------------+ +---------+ +--------------+ +-------------+ | 389 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 390 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 391 | | application | | | | applications | | application | | 392 | +-------------+ +---------+ +--------------+ +-------------+ | 393 | ^ ^ | 394 | | | | 395 | v v | 396 | +----------------------------------------------+ | 397 | | MIB instrumentation | SNMP entity | 398 +-------------------------------------------------------------------+ 400 3.1. Security Capabilities of this Model 402 3.1.1. Threats 404 The TLS Transport Model provides protection against the threats 405 identified by the RFC 3411 architecture [RFC3411]: 407 1. Modification of Information - The modification threat is the 408 danger that some unauthorized entity may alter in-transit SNMP 409 messages generated on behalf of an authorized principal in such a 410 way as to effect unauthorized management operations, including 411 falsifying the value of an object. 413 (D)TLS provides verification that the content of each received 414 message has not been modified during its transmission through the 415 network, data has not been altered or destroyed in an 416 unauthorized manner, and data sequences have not been altered to 417 an extent greater than can occur non-maliciously. 419 2. Masquerade - The masquerade threat is the danger that management 420 operations unauthorized for a given principal may be attempted by 421 assuming the identity of another principal that has the 422 appropriate authorizations. 424 The TLSTM provides for authentication of the Command Generator, 425 Command Responder, Notification Generator, Notification Responder 426 and Proxy Forwarder through the use of X.509 certificates. 428 The masquerade threat can be mitigated against by using an 429 appropriate Access Control Model (ACM) such as the View-based 430 Access Control Module (VACM) [RFC3415]. In addition, it is 431 important to authenticate and verify both the authenticated 432 identity of the (D)TLS client and the (D)TLS server to protect 433 against this threat. (See Section 9 for more detail.) 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]. The technique used is similar 448 to that as in IPsec AH/ESP [RFC4302] [RFC4303], by maintaining a 449 bitmap window of received records. Records that are too old to 450 fit in the window and records that have previously been received 451 are silently discarded. The replay detection feature is 452 optional, since packet duplication can also occur naturally due 453 to routing errors and does not necessarily indicate an active 454 attack. Applications may conceivably detect duplicate packets 455 and accordingly modify their data transmission strategy. 457 4. Disclosure - The disclosure threat is the danger of eavesdropping 458 on the exchanges between SNMP engines. Protecting against this 459 threat may be required by local policy at the deployment site. 461 Symmetric cryptography (e.g., AES [AES], DES [DES] etc.) can be 462 used by (D)TLS for data privacy. The keys for this symmetric 463 encryption are generated uniquely for each session and are based 464 on a secret negotiated by another protocol (such as the (D)TLS 465 Handshake Protocol). 467 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 468 that denial of service (DoS) attacks need not be addressed by an 469 SNMP security protocol. However, datagram-based security 470 protocols like DTLS are susceptible to a variety of denial of 471 service attacks because it is more vulnerable to spoofed 472 messages. 474 In order to counter both of these attacks, DTLS borrows the 475 stateless cookie technique used by Photuris [RFC2522] and IKEv2 476 [RFC4306] and is described fully in section 4.2.1 of [RFC4347]. 477 This mechanism, though, does not provide any defense against 478 denial of service attacks mounted from valid IP addresses. DTLS 479 Transport Model server implementations MUST support DTLS cookies. 481 Implementations are not required to perform the stateless cookie 482 exchange for every DTLS handshakes but in environments where 483 amplification could be an issue or has been detected it is 484 RECOMMENDED that the cookie exchange is utilized. 486 3.1.2. Message Protection 488 The RFC 3411 architecture recognizes three levels of security: 490 o without authentication and without privacy (noAuthNoPriv) 492 o with authentication but without privacy (authNoPriv) 494 o with authentication and with privacy (authPriv) 496 The TLS Transport Model determines from (D)TLS the identity of the 497 authenticated principal, and the type and address associated with an 498 incoming message, and the TLS Transport Model provides this 499 information to (D)TLS for an outgoing message. 501 When an application requests a session for a message, through the 502 cache, the application requests a security level for that session. 503 The TLS Transport Model MUST ensure that the (D)TLS session provides 504 security at least as high as the requested level of security. How 505 the security level is translated into the algorithms used to provide 506 data integrity and privacy is implementation-dependent. However, the 507 NULL integrity and encryption algorithms MUST NOT be used to fulfill 508 security level requests for authentication or privacy. 509 Implementations MAY choose to force (D)TLS to only allow 510 cipher_suites that provide both authentication and privacy to 511 guarantee this assertion. 513 If a suitable interface between the TLS Transport Model and the 514 (D)TLS Handshake Protocol is implemented to allow the selection of 515 security level dependent algorithms, for example a security level to 516 cipher_suites mapping table, then different security levels may be 517 utilized by the application. However, different port numbers will 518 need to be used by at least one side of the connection to 519 differentiate between the (D)TLS sessions. This is the only way to 520 ensured proper selection of a session ID for an incoming (D)TLS 521 message. 523 The authentication, integrity and privacy algorithms used by the 524 (D)TLS Protocol [RFC4347] may vary over time as the science of 525 cryptography continues to evolve and the development of (D)TLS 526 continues over time. Implementers are encouraged to plan for changes 527 in operator trust of particular algorithms and implementations should 528 offer configuration settings for mapping algorithms to SNMPv3 529 security levels. 531 3.1.3. (D)TLS Sessions 533 (D)TLS sessions are opened by the TLS Transport Model during the 534 elements of procedure for an outgoing SNMP message. Since the sender 535 of a message initiates the creation of a (D)TLS session if needed, 536 the (D)TLS session will already exist for an incoming message. 538 Implementations MAY choose to instantiate (D)TLS sessions in 539 anticipation of outgoing messages. This approach might be useful to 540 ensure that a (D)TLS session to a given target can be established 541 before it becomes important to send a message over the (D)TLS 542 session. Of course, there is no guarantee that a pre-established 543 session will still be valid when needed. 545 DTLS sessions, when used over UDP, are uniquely identified within the 546 TLS Transport Model by the combination of transportDomain, 547 transportAddress, securityName, and requestedSecurityLevel associated 548 with each session. Each unique combination of these parameters MUST 549 have a locally-chosen unique dtlsSessionID associated for active 550 sessions. For further information see Section 4.4 and Section 5. 551 TLS and DTLS over SCTP sessions, on the other hand, do not require a 552 unique paring of attributes since their lower layer protocols (TCP 553 and SCTP) already provide adequate session framing. 555 3.2. Security Parameter Passing 557 For the (D)TLS server-side, (D)TLS-specific security parameters 558 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 559 are translated by the TLS Transport Model into security parameters 560 for the TLS Transport Model and security model (i.e., securityLevel, 561 securityName, transportDomain, transportAddress). The transport- 562 related and (D)TLS-security-related information, including the 563 authenticated identity, are stored in a cache referenced by 564 tmStateReference. 566 For the (D)TLS client-side, the TLS Transport Model takes input 567 provided by the dispatcher in the sendMessage() Abstract Service 568 Interface (ASI) and input from the tmStateReference cache. The 569 (D)TLS Transport Model converts that information into suitable 570 security parameters for (D)TLS and establishes sessions as needed. 572 The elements of procedure in Section 5 discuss these concepts in much 573 greater detail. 575 3.3. Notifications and Proxy 577 (D)TLS sessions may be initiated by (D)TLS clients on behalf of 578 command generators or notification originators. Command generators 579 are frequently operated by a human, but notification originators are 580 usually unmanned automated processes. The targets to whom 581 notifications should be sent is typically determined and configured 582 by a network administrator. 584 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 585 management targets, including transportDomain, transportAddress, 586 securityName, securityModel, and securityLevel parameters, for 587 Notification Generator, Proxy Forwarder, and SNMP-controllable 588 Command Generator applications. Transport domains and transport 589 addresses are configured in the snmpTargetAddrTable, and the 590 securityModel, securityName, and securityLevel parameters are 591 configured in the snmpTargetParamsTable. This document defines a MIB 592 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 593 specify a (D)TLS client-side certificate to use for the connection. 595 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 596 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 597 set to the snmpTLSDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 598 object and an appropriate snmpTLSAddress, snmpDTLSUDPAddress or 599 snmpDTLSSCTPAddress value respectively. The snmpTargetParamsMPModel 600 column of the snmpTargetParamsTable should be set to a value of 3 to 601 indicate the SNMPv3 message processing model. The 602 snmpTargetParamsSecurityName should be set to an appropriate 603 securityName value and the tlstmParamsClientHashType and 604 tlstmParamsClientHashValue parameters of the tlstmParamsTable should 605 be set to values that refer to a locally held certificate to be used. 606 The tlstmAddrServerHashType and tlstmAddrServerHashValue must be set 607 to a hash value that refers to a locally held copy of the server's 608 presented identity certificate. Other parameters, for example 609 cryptographic configuration such as cipher suites to use, must come 610 from configuration mechanisms not defined in this document. The 611 other needed configuration may be configured using SNMP or other 612 implementation-dependent mechanisms (for example, via a CLI). This 613 securityName defined in the snmpTargetParamsSecurityName column will 614 be used by the access control model to authorize any notifications 615 that need to be sent. 617 4. Elements of the Model 619 This section contains definitions required to realize the (D)TLS 620 Transport Model defined by this document. 622 4.1. X.509 Certificates 624 (D)TLS makes use of X.509 certificates for authentication of both 625 sides of the transport. This section discusses the use of 626 certificates in the TLSTM. An overview of X.509 certificate 627 infrastructure can be found in Appendix B. 629 4.1.1. Provisioning for the Certificate 631 Authentication using (D)TLS will require that SNMP entities are 632 provisioned with certificates, which are signed by trusted 633 certificate authorities. Furthermore, SNMP entities will most 634 commonly need to be provisioned with root certificates which 635 represent the list of trusted certificate authorities that an SNMP 636 entity can use for certificate verification. SNMP entities SHOULD 637 also be provisioned with a X.509 certificate revocation mechanism 638 which can be used to verify that a certificate has not been revoked. 640 The authenticated tmSecurityName of the principal is looked up using 641 the tlstmCertToSNTable. This table either: 643 o Maps a certificate's fingerprint hash type and value to a directly 644 specified tmSecurityName. 646 o Identifies a certificate issuer's fingerprint hash type and value 647 and allows child certificate's subjectAltName or CommonName to 648 directly used as the tmSecurityNome. 650 The certificate trust anchors, being either CA certificates or public 651 keys for use by self-signed certificates, must be installed through 652 an out of band trusted mechanism into the server and its authenticity 653 MUST be verified before access is granted. Implementations SHOULD 654 choose to discard any connections for which no potential 655 tlstmCertToSNTable mapping exists before performing certificate 656 verification to avoid expending computational resources associated 657 with certificate verification. 659 The typical enterprise configuration will map a "subjectAltName" 660 component of the tbsCertificate to the TLSTM specific tmSecurityName. 661 Thus, the authenticated identity can be obtained by the TLS Transport 662 Model by extracting the subjectAltName(s) from the peer's certificate 663 and the receiving application will have an appropriate tmSecurityName 664 for use by components like an access control model. This setup 665 requires very little configuration: a single row in the 666 tlstmCertToSNTable referencing a certificate authority. 668 An example mapping setup can be found in Appendix C 670 This tmSecurityName may be later translated from a TLSTM specific 671 tmSecurityName to a SNMP engine securityName by the security model. 672 A security model, like the TSM security model, may perform an 673 identity mapping or a more complex mapping to derive the securityName 674 from the tmSecurityName offered by the TLS Transport Model. 676 4.2. Messages 678 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 679 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 680 messages from being sent that exceeds the maximum DTLS message size. 681 The TLSTM implementation SHOULD return an error when the DTLS message 682 size would be exceeded and the message won't be sent. 684 4.3. SNMP Services 686 This section describes the services provided by the (D)TLS Transport 687 Model with their inputs and outputs. The services are between the 688 Transport Model and the dispatcher. 690 The services are described as primitives of an abstract service 691 interface (ASI) and the inputs and outputs are described as abstract 692 data elements as they are passed in these abstract service 693 primitives. 695 4.3.1. SNMP Services for an Outgoing Message 697 The dispatcher passes the information to the TLS Transport Model 698 using the ASI defined in the transport subsystem: 700 statusInformation = 701 sendMessage( 702 IN destTransportDomain -- transport domain to be used 703 IN destTransportAddress -- transport address to be used 704 IN outgoingMessage -- the message to send 705 IN outgoingMessageLength -- its length 706 IN tmStateReference -- reference to transport state 707 ) 709 The abstract data elements passed as parameters in the abstract 710 service primitives are as follows: 712 statusInformation: An indication of whether the passing of the 713 message was successful. If not it is an indication of the 714 problem. 716 destTransportDomain: The transport domain for the associated 717 destTransportAddress. The Transport Model uses this parameter to 718 determine the transport type of the associated 719 destTransportAddress. This parameter may also be used by the 720 transport subsystem to route the message to the appropriate 721 Transport Model. This document specifies three TLS and DTLS based 722 Transport Domains for use: the snmpTLSDomain, the 723 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 725 destTransportAddress: The transport address of the destination TLS 726 Transport Model in a format specified by the SnmpTLSAddress, the 727 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTIONs. 729 outgoingMessage: The outgoing message to send to (D)TLS for 730 encapsulation. 732 outgoingMessageLength: The length of the outgoing message. 734 tmStateReference: A handle/reference to tmSecurityData to be used 735 when securing outgoing messages. 737 4.3.2. SNMP Services for an Incoming Message 739 The TLS Transport Model processes the received message from the 740 network using the (D)TLS service and then passes it to the dispatcher 741 using the following ASI: 743 statusInformation = 744 receiveMessage( 745 IN transportDomain -- origin transport domain 746 IN transportAddress -- origin transport address 747 IN incomingMessage -- the message received 748 IN incomingMessageLength -- its length 749 IN tmStateReference -- reference to transport state 750 ) 752 The abstract data elements passed as parameters in the abstract 753 service primitives are as follows: 755 statusInformation: An indication of whether the passing of the 756 message was successful. If not it is an indication of the 757 problem. 759 transportDomain: The transport domain for the associated 760 transportAddress. This document specifies three TLS and DTLS 761 based Transport Domains for use: the snmpTLSDomain, the 762 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 764 transportAddress: The transport address of the source of the 765 received message in a format specified by the SnmpTLSAddress, the 766 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 768 incomingMessage: The whole SNMP message stripped of all (D)TLS 769 protection data. 771 incomingMessageLength: The length of the SNMP message after being 772 processed by (D)TLS. 774 tmStateReference: A handle/reference to tmSecurityData to be used by 775 the security model. 777 4.4. (D)TLS Services 779 This section describes the services provided by the (D)TLS Transport 780 Model with their inputs and outputs. These services are between the 781 TLS Transport Model and the (D)TLS transport layer. The following 782 sections describe services for establishing and closing a session and 783 for passing messages between the (D)TLS transport layer and the TLS 784 Transport Model. 786 4.4.1. Services for Establishing a Session 788 The TLS Transport Model provides the following ASI to describe the 789 data passed between the Transport Model and the (D)TLS transport 790 layer for session establishment. 792 statusInformation = -- errorIndication or success 793 openSession( 794 IN destTransportDomain -- transport domain to be used 795 IN destTransportAddress -- transport address to be used 796 IN securityName -- on behalf of this principal 797 IN securityLevel -- Level of Security requested 798 OUT tlsSessionID -- Session identifier for (D)TLS 799 ) 801 The abstract data elements passed as parameters in the abstract 802 service primitives are as follows: 804 statusInformation: An indication of whether the process was 805 successful or not. If not, then the status information will 806 include the error indication provided by (D)TLS. 808 destTransportDomain: The transport domain for the associated 809 destTransportAddress. The TLS Transport Model uses this parameter 810 to determine the transport type of the associated 811 destTransportAddress. This document specifies three TLS and DTLS 812 based Transport Domains for use: the snmpTLSDomain, the 813 snmpDTLSUDPDomain, and the snmpDTLSSCTPDomain. 815 destTransportAddress: The transport address of the destination TLS 816 Transport Model in a format specified by the SnmpTLSAddress, the 817 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 819 securityName: The security name representing the principal on whose 820 behalf the message will be sent. 822 securityLevel: The level of security requested by the application. 824 dtlsSessionID: An implementation-dependent session identifier to 825 reference the specific (D)TLS session. 827 DTLS and UDP do not provide a session de-multiplexing mechanism and 828 it is possible that implementations will only be able to identify a 829 unique session based on a unique combination of source address, 830 destination address, source UDP port number and destination UDP port 831 number. Because of this, when establishing a new sessions 832 implementations MUST use a different UDP source port number for each 833 connection to a remote destination IP-address/port-number combination 834 to ensure the remote entity can properly disambiguate between 835 multiple sessions from a host to the same port on a server. TLS and 836 DTLS over SCTP provide session de-multiplexing so this restriction is 837 not needed for TLS or DTLS over SCTP implementations. 839 The procedural details for establishing a session are further 840 described in Section 5.3. 842 Upon completion of the process the TLS Transport Model returns status 843 information and, if the process was successful the dtlsSessionID. 844 Other implementation-dependent data from (D)TLS are also returned. 845 The dtlsSessionID is stored in an implementation- dependent manner 846 and tied to the tmSecurityData for future use of this session. 848 4.4.2. (D)TLS Services for an Incoming Message 850 When the TLS Transport Model invokes the (D)TLS record layer to 851 verify proper security for the incoming message, it must use the 852 following ASI: 854 statusInformation = -- errorIndication or success 855 tlsRead( 856 IN tlsSessionID -- Session identifier for (D)TLS 857 IN wholeTlsMsg -- as received on the wire 858 IN wholeTlsMsgLength -- length as received on the wire 859 OUT incomingMessage -- the whole SNMP message from (D)TLS 860 OUT incomingMessageLength -- the length of the SNMP message 861 ) 863 The abstract data elements passed as parameters in the abstract 864 service primitives are as follows: 866 statusInformation: An indication of whether the process was 867 successful or not. If not, then the status information will 868 include the error indication provided by (D)TLS. 870 tlsSessionID: An implementation-dependent session identifier to 871 reference the specific (D)TLS session. How the (D)TLS session ID 872 is obtained for each message is implementation-dependent. As an 873 implementation hint, for dtls over udp the TLS Transport Model can 874 examine incoming messages to determine the source IP address, 875 source port number, destination IP address, and destination port 876 number and use these values to look up the local tlsSessionID in 877 the list of active sessions. 879 wholeDtlsMsg: The whole message as received on the wire. 881 wholeDtlsMsgLength: The length of the message as it was received on 882 the wire. 884 incomingMessage: The whole SNMP message stripped of all (D)TLS 885 privacy and integrity data. 887 incomingMessageLength: The length of the SNMP message stripped of 888 all (D)TLS privacy and integrity data. 890 4.4.3. (D)TLS Services for an Outgoing Message 892 When the TLS Transport Model invokes the (D)TLS record layer to 893 encapsulate and transmit a SNMP message, it must use the following 894 ASI. 896 statusInformation = -- errorIndication or success 897 tlsWrite( 898 IN tlsSessionID -- Session identifier for (D)TLS 899 IN outgoingMessage -- the message to send 900 IN outgoingMessageLength -- its length 901 ) 903 The abstract data elements passed as parameters in the abstract 904 service primitives are as follows: 906 statusInformation: An indication of whether the process was 907 successful or not. If not, then the status information will 908 include the error indication provided by (D)TLS. 910 tlsSessionID: An implementation-dependent session identifier to 911 reference the specific (D)TLS session that the message should be 912 sent using. 914 outgoingMessage: The outgoing message to send to (D)TLS for 915 encapsulation. 917 outgoingMessageLength: The length of the outgoing message. 919 4.5. Cached Information and References 921 When performing SNMP processing, there are two levels of state 922 information that may need to be retained: the immediate state linking 923 a request-response pair, and potentially longer-term state relating 924 to transport and security. "Transport Subsystem for the Simple 925 Network Management Protocol" [I-D.ietf-isms-tmsm] defines general 926 requirements for caches and references. 928 4.5.1. TLS Transport Model Cached Information 930 The TLSTM has no specific responsibilities regarding the cached 931 information beyond those discussed in "Transport Subsystem for the 932 Simple Network Management Protocol" [I-D.ietf-isms-tmsm] 934 5. Elements of Procedure 936 Abstract service interfaces have been defined by RFC 3411 to describe 937 the conceptual data flows between the various subsystems within an 938 SNMP entity. The TLSTM uses some of these conceptual data flows when 939 communicating between subsystems. These RFC 3411-defined data flows 940 are referred to here as public interfaces. 942 To simplify the elements of procedure, the release of state 943 information is not always explicitly specified. As a general rule, 944 if state information is available when a message gets discarded, the 945 message-state information should also be released. If state 946 information is available when a session is closed, the session state 947 information should also be released. Sensitive information, like 948 cryptographic keys, should be overwritten appropriately first prior 949 to being released. 951 An error indication may return an OID and value for an incremented 952 counter if the information is available at the point where the error 953 is detected. 955 5.1. Procedures for an Incoming Message 957 This section describes the procedures followed by the (D)TLS 958 Transport Model when it receives a (D)TLS protected packet. The 959 steps are broken into two different sections. Section 5.1.1 960 describes the needed steps for de-multiplexing multiple DTLS 961 sessions, which is specifically needed for DTLS over UDP sessions. 962 Section 5.1.2 describes the steps specific to transport processing 963 once the (D)TLS processing has been completed. 965 5.1.1. DTLS Processing for Incoming Messages 967 DTLS is significantly different in terms of session handling than 968 TCP-based session streams like SSH or TLS. The DTLS protocol, which 969 is datagram-based, does not have a session identifier when run over 970 UDP that allows implementations to determine through what session a 971 packet arrived. DTLS over SCTP and TLS over TCP streams have built 972 in session demultiplexing and thus the steps in this section are not 973 necessary for those protocol combinations. It is always critical, 974 however, that implementations be able to derive a tlsSessionID from 975 any demultiplexing process. 977 A process for de-multiplexing multiple DTLS sessions arriving over 978 UDP must be incorporated into the procedures for processing an 979 incoming message. The steps in this section describe how this can be 980 accomplished, although any implementation dependent method should be 981 suitable as long as the results are consistently deterministic. The 982 important output results from the steps in this process are the 983 transportDomain, the transportAddress, the wholeMessage, the 984 wholeMessageLength, and a unique implementation-dependent session 985 identifier (tlsSessionID). 987 This demultiplexing procedure assumes that upon session establishment 988 an entry in a local transport mapping table is created in the 989 Transport Model's Local Configuration Datastore (LCD). The transport 990 mapping table's entry should map a unique combination of the remote 991 address, remote port number, local address and local port number to a 992 implementation-dependent tlsSessionID. 994 1) The TLS Transport Model examines the raw UDP message, in an 995 implementation-dependent manner. If the message is not a DTLS 996 message then it should be discarded. If the message is not a 997 (D)TLS Application Data message then the message should be 998 processed by the underlying DTLS framework as it is (for example) 999 a session initialization or session modification message and no 1000 further steps below should be taken by the DTLS Transport. 1002 2) The TLS Transport Model queries the LCD using the transport 1003 parameters (source and destination addresses and ports) to 1004 determine if a session already exists and its tlsSessionID. 1006 3) If a matching entry in the LCD does not exist then the message is 1007 discarded. Increment the tlstmSessionNoAvailableSessions counter 1008 and stop processing the message. 1010 Note that an entry would already exist if the client and server's 1011 session establishment procedures had been successfully completed 1012 (as described both above and in Section 5.3) even if no message 1013 had yet been sent through the newly established session. An 1014 entry may not exist, however, if a "rogue" message was routed to 1015 the SNMP entity by mistake. An entry might also be missing 1016 because of a "broken" session (see operational considerations). 1018 4) Retrieve the tlsSessionID from the LCD. 1020 5) The tlsWholeMsg, and the tlsSessionID are passed to DTLS for 1021 integrity checking and decryption using the tlsRead() ASI. 1023 6) If the message fails integrity checks or other (D)TLS security 1024 processing then the tlstmDTLSProtectionErrors counter is 1025 incremented, the message is discarded and processing of the 1026 message is stopped. 1028 7) The output of the tlsRead results in an incomingMessage and an 1029 incomingMessageLength. These results and the tlsSessionID are 1030 used below in the Section 5.1.2 to complete the processing of the 1031 incoming message. 1033 5.1.2. Transport Processing for Incoming Messages 1035 The procedures in this section describe how the TLS Transport Model 1036 should process messages that have already been properly extracted 1037 from the (D)TLS stream. 1039 Create a tmStateReference cache for the subsequent reference and 1040 assign the following values within it: 1042 tmTransportDomain = snmpTLSDomain, snmpDTLSUDPDomain or 1043 snmpDTLSSCTPDomain as appropriate. 1045 tmTransportAddress = The address the message originated from, 1046 determined in an implementation dependent way. 1048 tmSecurityLevel = The derived tmSecurityLevel for the session, as 1049 discussed in Section 3.1.2 and Section 5.3. 1051 tmSecurityName = The derived tmSecurityName for the session as 1052 discussed in and Section 5.3. This value MUST be constant during 1053 the lifetime of the (D)TLS session. 1055 tmSessionID = The tlsSessionID, which MUST be a unique session 1056 identifier for this (D)TLS session. The contents and format of 1057 this identifier are implementation dependent as long as it is 1058 unique to the session. A session identifier MUST NOT be reused 1059 until all references to it are no longer in use. The tmSessionID 1060 is equal to the tlsSessionID discussed in Section 5.1.1. 1061 tmSessionID refers to the session identifier when stored in the 1062 tmStateReference and tlsSessionID refers to the session identifier 1063 when stored in the LCD. They MUST always be equal when processing 1064 a given session's traffic. 1066 The wholeMessage and the wholeMessageLength are assigned values from 1067 the incomingMessage and incomingMessageLength values from the (D)TLS 1068 processing. 1070 The TLS Transport Model passes the transportDomain, transportAddress, 1071 wholeMessage, and wholeMessageLength to the dispatcher using the 1072 receiveMessage ASI: 1074 statusInformation = 1075 receiveMessage( 1076 IN transportDomain -- snmpTLSDomain, snmpDTLSUDPDomain, 1077 -- or snmpDTLSSCTPDomain 1078 IN transportAddress -- address for the received message 1079 IN wholeMessage -- the whole SNMP message from (D)TLS 1080 IN wholeMessageLength -- the length of the SNMP message 1081 IN tmStateReference -- (NEW) transport info 1082 ) 1084 5.2. Procedures for an Outgoing Message 1086 The dispatcher sends a message to the TLS Transport Model using the 1087 following ASI: 1089 statusInformation = 1090 sendMessage( 1091 IN destTransportDomain -- transport domain to be used 1092 IN destTransportAddress -- transport address to be used 1093 IN outgoingMessage -- the message to send 1094 IN outgoingMessageLength -- its length 1095 IN tmStateReference -- (NEW) transport info 1096 ) 1098 This section describes the procedure followed by the TLS Transport 1099 Model whenever it is requested through this ASI to send a message. 1101 1) Extract tmSessionID, tmTransportAddress, tmSecurityName, 1102 tmRequestedSecurityLevel. and tmSameSecurity from the 1103 tmStateReference. Note: The tmSessionID value may be undefined 1104 if session exists yet. 1106 2) If tmSameSecurity is true and either tmSessionID is undefined or 1107 refers to a session that is no longer open then increment the 1108 tlstmSessionNoAvailableSessions counter, discard the message and 1109 return the error indication in the statusInformation. Processing 1110 of this message stops. 1112 3) If tmSameSecurity is false and tmSessionID refers to a session 1113 that is no longer available then an implementation SHOULD open a 1114 new session using the openSession() ASI as described below in 1115 step 4b. An implementation MAY choose to return an error to the 1116 calling module. 1118 4) If tmSessionID is undefined, then use tmTransportAddress, 1119 tmSecurityName and tmRequestedSecurityLevel to see if there is a 1120 corresponding entry in the LCD suitable to send the message over. 1122 4a) If there is a corresponding LCD entry, then this session 1123 will be used to send the message. 1125 4b) If there is not a corresponding LCD entry, then open a 1126 session using the openSession() ASI (discussed further in 1127 Section 4.4.1). Implementations MAY wish to offer message 1128 buffering to prevent redundant openSession() calls for the 1129 same cache entry. If an error is returned from 1130 OpenSession(), then discard the message, increment the 1131 tlstmSessionOpenErrors, and return an error indication to 1132 the calling module. 1134 5) Using either the session indicated by the tmSessionID if there 1135 was one or the session resulting in the previous step, pass the 1136 outgoingMessage to (D)TLS for encapsulation and transmission. 1138 5.3. Establishing a Session 1140 The TLS Transport Model provides the following primitive to establish 1141 a new (D)TLS session (previously discussed in Section 4.4.1): 1143 statusInformation = -- errorIndication or success 1144 openSession( 1145 IN destTransportDomain -- transport domain to be used 1146 IN destTransportAddress -- transport address to be used 1147 IN securityName -- on behalf of this principal 1148 IN securityLevel -- Level of Security requested 1149 OUT tlsSessionID -- Session identifier for (D)TLS 1150 ) 1152 The following describes the procedure to follow to establish a SNMP 1153 over (D)TLS session between SNMP engines to exchange SNMP messages. 1154 This process is followed by any SNMP engine establishing a session 1155 for subsequent use. 1157 This MAY be done automatically for SNMP messages which are not 1158 Response or Report messages. 1160 (D)TLS provides no explicit manner for transmitting an identity the 1161 client wishes to connect to during or prior to key exchange to 1162 facilitate certificate selection at the server (e.g. at a 1163 Notification Receiver). I.E., there is no available mechanism for 1164 sending notifications to a specific principal at a given TCP, UDP or 1165 SCTP port. Therefore, implementations MAY support responding with 1166 multiple identities using separate TCP, UDP or SCTP port numbers to 1167 indicate the desired principal or some other implementation-dependent 1168 solution. 1170 1) The client selects the appropriate certificate and cipher_suites 1171 for the key agreement based on the tmSecurityName and the 1172 tmRequestedSecurityLevel for the session. For sessions being 1173 established as a result of a SNMP-TARGET-MIB based operation, the 1174 certificate will potentially have been identified via the 1175 tlstmParamsTable mapping and the cipher_suites will have to be 1176 taken from system-wide or implementation-specific configuration. 1177 Otherwise, the certificate and appropriate cipher_suites will 1178 need to be passed to the openSession() ASI as supplemental 1179 information or configured through an implementation-dependent 1180 mechanism. It is also implementation-dependent and possibly 1181 policy-dependent how tmRequestedSecurityLevel will be used to 1182 influence the security capabilities provided by the (D)TLS 1183 session. However this is done, the security capabilities 1184 provided by (D)TLS MUST be at least as high as the level of 1185 security indicated by the tmRequestedSecurityLevel parameter. 1186 The actual security level of the session should be reported in 1187 the tmStateReference cache as tmSecurityLevel. For (D)TLS to 1188 provide strong authentication, each principal acting as a Command 1189 Generator SHOULD have its own certificate. 1191 2) Using the destTransportDomain and destTransportAddress values, 1192 the client will initiate the (D)TLS handshake protocol to 1193 establish session keys for message integrity and encryption. 1195 If the attempt to establish a session is unsuccessful, then 1196 tlstmSessionOpenErrors is incremented, an error indication is 1197 returned, and session establishment processing stops. 1199 3) Once the secure session is established and both sides have been 1200 authenticated, certificate validation and identity expectations 1201 are performed. 1203 a) The (D)TLS server side of the connection identifies the 1204 authenticated identity from the (D)TLS client's principal 1205 certificate using appropriate certificate path validation 1206 procedures (e.g. [RFC5280]) using configuration information 1207 from the tlstmCertToSNTable mapping table. The resulting 1208 derived securityName is recorded in the tmStateReference 1209 cache as tmSecurityName. The details of the lookup process 1210 are fully described in the DESCRIPTION clause of the 1211 tlstmCertToSNTable MIB object. If this verification fails in 1212 any way (for example because of failures in cryptographic 1213 verification or the lack of an appropriate row in the 1214 tlstmCertToSNTable) then the session establishment MUST fail, 1215 the tlstmSessionInvalidClientCertificates object is 1216 incremented and processing is stopped. 1218 b) The (D)TLS client side of the connection SHOULD verify that 1219 authenticated identity of the (D)TLS server's certificate is 1220 the certificate expected. This can be done using the 1221 configuration found in the tlstmAddrTable if the client is 1222 establishing the connection based on SNMP-TARGET-MIB 1223 configuration. The client MUST always perform appropriate 1224 certificate path validation procedures (e.g. [RFC5280]) to 1225 ensure the certificate is cryptographically valid. 1227 If strong authentication is desired then the (D)TLS server 1228 address or naming mechanism MUST always be verified against 1229 the certificate's contents. Methods for doing this are 1230 described in [I-D.saintandre-tls-server-id-check]. Matching 1231 the server's naming against SubjectAltName extension values 1232 is the preferred mechanism for comparison, but matching the 1233 CommonName MAY be used. 1235 (D)TLS provides assurance that the authenticated identity has 1236 been signed by a trusted configured certificate authority. 1237 If verification of the server's certificate fails in any way 1238 (for example because of failures in cryptographic 1239 verification or the presented identity was not the expected 1240 identity) then the session establishment MUST fail, the 1241 tlstmSessionInvalidServerCertificates object is incremented 1242 and processing is stopped. 1244 4) The (D)TLS-specific session identifier is passed to the TLS 1245 Transport Model and associated with the tmStateReference cache 1246 entry to indicate that the session has been established 1247 successfully and to point to a specific (D)TLS session for future 1248 use. 1250 5.4. Closing a Session 1252 The TLS Transport Model provides the following primitive to close a 1253 session: 1255 statusInformation = 1256 closeSession( 1257 IN tmStateReference -- transport info 1258 ) 1260 The following describes the procedure to follow to close a session 1261 between a client and server. This process is followed by any SNMP 1262 engine closing the corresponding SNMP session. 1264 1) Look up the session in the cache and the LCD using the 1265 tmStateReference. 1267 2) If there is no session open associated with the tmStateReference, 1268 then closeSession processing is completed. 1270 3) Delete the entry from the cache and any other implementation- 1271 dependent information in the LCD. 1273 4) Have (D)TLS close the specified session. This SHOULD include 1274 sending a close_notify TLS Alert to inform the other side that 1275 session cleanup may be performed. 1277 6. MIB Module Overview 1279 This MIB module provides management of the TLS Transport Model. It 1280 defines needed textual conventions, statistical counters and 1281 configuration infrastructure necessary for session establishment. 1282 Example usage of the configuration tables can be found in Appendix C. 1284 6.1. Structure of the MIB Module 1286 Objects in this MIB module are arranged into subtrees. Each subtree 1287 is organized as a set of related objects. The overall structure and 1288 assignment of objects to their subtrees, and the intended purpose of 1289 each subtree, is shown below. 1291 6.2. Textual Conventions 1293 Generic and Common Textual Conventions used in this module can be 1294 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1296 This module defines the following new Textual Conventions: 1298 o A new TransportDomain and TransportAddress format for describing 1299 (D)TLS connection addressing requirements. 1301 o Public certificate fingerprint Hashing Types and Values. These 1302 textual conventions allow for MIB module objects to refer 1303 generically to a stored X.509 certificate using a simple hash 1304 value as a reference pointer. 1306 6.3. Statistical Counters 1308 The TLSTM-MIB defines some statical counters that can provide network 1309 managers with feedback about (D)TLS session usage and potential 1310 errors that a MIB-instrumented device may be experiencing. 1312 6.4. Configuration Tables 1314 The TLSTM-MIB defines configuration tables that a manager can use for 1315 help in configuring a MIB-instrumented device for sending and 1316 receiving SNMP messages over (D)TLS. In particular, there is a MIB 1317 table that extends the SNMP-TARGET-MIB for configuring certificates 1318 to be used and a MIB table for mapping incoming (D)TLS client 1319 certificates to securityNames. 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 assumed 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 SNMP-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 1347 FROM SNMPv2-SMI 1348 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType 1349 FROM SNMPv2-TC 1350 MODULE-COMPLIANCE, OBJECT-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 " " 1361 CONTACT-INFO "WG-EMail: 1362 Subscribe: 1364 Chairs: 1365 Co-editors: 1366 " 1368 DESCRIPTION "The TLS Transport Model MIB 1370 Copyright (C) The IETF Trust (2008). This 1371 version of this MIB module is part of RFC XXXX; 1372 see the RFC itself for full legal notices." 1373 -- NOTE to RFC editor: replace XXXX with actual RFC number 1374 -- for this document and remove this note 1376 REVISION "200807070000Z" 1377 DESCRIPTION "The initial version, published in RFC XXXX." 1378 -- NOTE to RFC editor: replace XXXX with actual RFC number 1379 -- for this document and remove this note 1381 ::= { snmpModules xxxx } 1382 -- RFC Ed.: replace xxxx with IANA-assigned number and 1383 -- remove this note 1385 -- ************************************************ 1386 -- subtrees of the SNMP-DTLS-TM-MIB 1387 -- ************************************************ 1389 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1390 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1391 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1393 -- ************************************************ 1394 -- Objects 1395 -- ************************************************ 1397 snmpTLSDomain OBJECT-IDENTITY 1398 STATUS current 1399 DESCRIPTION 1400 "The SNMP over TLS transport domain. The corresponding 1401 transport address is of type SnmpTLSAddress. 1403 The securityName prefix to be associated with the 1404 snmpTLSDomain is 'tls'. This prefix may be used by 1405 security models or other components to identify what secure 1406 transport infrastructure authenticated a securityName." 1408 ::= { snmpDomains xx } 1410 -- RFC Ed.: replace xx with IANA-assigned number and 1411 -- remove this note 1413 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1414 -- if 'tls' is not assigned to this document. 1416 snmpDTLSUDPDomain OBJECT-IDENTITY 1417 STATUS current 1418 DESCRIPTION 1419 "The SNMP over DTLS/UDP transport domain. The corresponding 1420 transport address is of type SnmpDTLSUDPAddress. 1422 When an SNMP entity uses the snmpDTLSUDPDomain transport 1423 model, it must be capable of accepting messages up to 1424 the maximum MTU size for an interface it supports, minus the 1425 needed IP, UDP, DTLS and other protocol overheads. 1427 The securityName prefix to be associated with the 1428 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1429 security models or other components to identify what secure 1430 transport infrastructure authenticated a securityName." 1432 ::= { snmpDomains yy } 1434 -- RFC Ed.: replace yy with IANA-assigned number and 1435 -- remove this note 1437 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1438 -- if 'dtls' is not assigned to this document. 1440 snmpDTLSSCTPDomain OBJECT-IDENTITY 1441 STATUS current 1442 DESCRIPTION 1443 "The SNMP over DTLS/SCTP transport domain. The corresponding 1444 transport address is of type SnmpDTLSSCTPAddress. 1446 When an SNMP entity uses the snmpDTLSSCTPDomain transport 1447 model, it must be capable of accepting messages up to 1448 the maximum MTU size for an interface it supports, minus the 1449 needed IP, SCTP, DTLS and other protocol overheads. 1451 The securityName prefix to be associated with the 1452 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1453 security models or other components to identify what secure 1454 transport infrastructure authenticated a securityName." 1456 ::= { snmpDomains zz } 1458 -- RFC Ed.: replace zz with IANA-assigned number and 1459 -- remove this note 1461 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1462 -- if 'dtls' is not assigned to this document. 1464 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1465 DISPLAY-HINT "1a" 1466 STATUS current 1467 DESCRIPTION 1468 "Represents a TCP connection address for an IPv4 address, an 1469 IPv6 address or an ASCII encoded host name and port number. 1471 The hostname must be encoded in ASCII, as specified in RFC3490 1472 (Internationalizing Domain Names in Applications) followed by 1473 a colon ':' (ASCII character 0x3A) and a decimal port number 1474 in ASCII. The name SHOULD be fully qualified whenever 1475 possible. 1477 An IPv4 address must be a dotted decimal format followed by a 1478 colon ':' (ASCII character 0x3A) and a decimal port number in 1479 ASCII. 1481 An IPv6 address must be a colon separated format, surrounded 1482 by square brackets (ASCII characters 0x5B and 0x5D), followed 1483 by a colon ':' (ASCII character 0x3A) and a decimal port 1484 number in ASCII. 1486 Values of this textual convention may not be directly usable 1487 as transport-layer addressing information, and may require 1488 run-time resolution. As such, applications that write them 1489 must be prepared for handling errors if such values are not 1490 supported, or cannot be resolved (if resolution occurs at the 1491 time of the management operation). 1493 The DESCRIPTION clause of TransportAddress objects that may 1494 have snmpTLSAddress values must fully describe how (and 1495 when) such names are to be resolved to IP addresses and vice 1496 versa. 1498 This textual convention SHOULD NOT be used directly in object 1499 definitions since it restricts addresses to a specific 1500 format. However, if it is used, it MAY be used either on its 1501 own or in conjunction with TransportAddressType or 1502 TransportDomain as a pair. 1504 When this textual convention is used as a syntax of an index 1505 object, there may be issues with the limit of 128 1506 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1507 that all MIB documents using this textual convention make 1508 explicit any limitations on index component lengths that 1509 management software must observe. This may be done either by 1510 including SIZE constraints on the index components or by 1511 specifying applicable constraints in the conceptual row 1512 DESCRIPTION clause or in the surrounding documentation." 1513 SYNTAX OCTET STRING (SIZE (1..255)) 1515 SnmpDTLSUDPAddress ::= TEXTUAL-CONVENTION 1516 DISPLAY-HINT "1a" 1517 STATUS current 1518 DESCRIPTION 1519 "Represents a UDP connection address for an IPv4 address, an 1520 IPv6 address or an ASCII encoded host name and port number. 1522 The hostname must be encoded in ASCII, as specified in RFC3490 1523 (Internationalizing Domain Names in Applications) followed by 1524 a colon ':' (ASCII character 0x3A) and a decimal port number 1525 in ASCII. The name SHOULD be fully qualified whenever 1526 possible. 1528 An IPv4 address must be a dotted decimal format followed by a 1529 colon ':' (ASCII character 0x3A) and a decimal port number in 1530 ASCII. 1532 An IPv6 address must be a colon separated format, surrounded 1533 by square brackets (ASCII characters 0x5B and 0x5D), followed 1534 by a colon ':' (ASCII character 0x3A) and a decimal port 1535 number in ASCII. 1537 Values of this textual convention may not be directly usable 1538 as transport-layer addressing information, and may require 1539 run-time resolution. As such, applications that write them 1540 must be prepared for handling errors if such values are not 1541 supported, or cannot be resolved (if resolution occurs at the 1542 time of the management operation). 1544 The DESCRIPTION clause of TransportAddress objects that may 1545 have snmpDTLSUDPAddress values must fully describe how (and 1546 when) such names are to be resolved to IP addresses and vice 1547 versa. 1549 This textual convention SHOULD NOT be used directly in object 1550 definitions since it restricts addresses to a specific 1551 format. However, if it is used, it MAY be used either on its 1552 own or in conjunction with TransportAddressType or 1553 TransportDomain as a pair. 1555 When this textual convention is used as a syntax of an index 1556 object, there may be issues with the limit of 128 1557 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1558 that all MIB documents using this textual convention make 1559 explicit any limitations on index component lengths that 1560 management software must observe. This may be done either by 1561 including SIZE constraints on the index components or by 1562 specifying applicable constraints in the conceptual row 1563 DESCRIPTION clause or in the surrounding documentation." 1564 SYNTAX OCTET STRING (SIZE (1..255)) 1566 SnmpDTLSSCTPAddress ::= TEXTUAL-CONVENTION 1567 DISPLAY-HINT "1a" 1568 STATUS current 1569 DESCRIPTION 1570 "Represents a SCTP connection address for an IPv4 address, an 1571 IPv6 address or an ASCII encoded host name and port number. 1573 The hostname must be encoded in ASCII, as specified in RFC3490 1574 (Internationalizing Domain Names in Applications) followed by 1575 a colon ':' (ASCII character 0x3A) and a decimal port number 1576 in ASCII. The name SHOULD be fully qualified whenever 1577 possible. 1579 An IPv4 address must be a dotted decimal format followed by a 1580 colon ':' (ASCII character 0x3A) and a decimal port number in 1581 ASCII. 1583 An IPv6 address must be a colon separated format, surrounded 1584 by square brackets (ASCII characters 0x5B and 0x5D), followed 1585 by a colon ':' (ASCII character 0x3A) and a decimal port 1586 number in ASCII. 1588 Values of this textual convention may not be directly usable 1589 as transport-layer addressing information, and may require 1590 run-time resolution. As such, applications that write them 1591 must be prepared for handling errors if such values are not 1592 supported, or cannot be resolved (if resolution occurs at the 1593 time of the management operation). 1595 The DESCRIPTION clause of TransportAddress objects that may 1596 have snmpDTLSSCTPAddress values must fully describe how (and 1597 when) such names are to be resolved to IP addresses and vice 1598 versa. 1600 This textual convention SHOULD NOT be used directly in object 1601 definitions since it restricts addresses to a specific 1602 format. However, if it is used, it MAY be used either on its 1603 own or in conjunction with TransportAddressType or 1604 TransportDomain as a pair. 1606 When this textual convention is used as a syntax of an index 1607 object, there may be issues with the limit of 128 1608 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1609 that all MIB documents using this textual convention make 1610 explicit any limitations on index component lengths that 1611 management software must observe. This may be done either by 1612 including SIZE constraints on the index components or by 1613 specifying applicable constraints in the conceptual row 1614 DESCRIPTION clause or in the surrounding documentation." 1615 SYNTAX OCTET STRING (SIZE (1..255)) 1617 FingerprintType ::= TEXTUAL-CONVENTION 1618 STATUS current 1619 DESCRIPTION 1620 "Identifies an algorithm type that can be used to uniquely 1621 reference other data of a potentially arbitrary length. If a 1622 hashing algorithm is used, then the algorithm should be 1623 sufficiently robust enough and it's output long enough that 1624 hash-collisions should not occur. Other mechanisms of defining 1625 fingerprints include other forms of unique identification such 1626 as serial numbers or concatenated combinations of data such 1627 that the result is sufficiently unique. 1629 Objects making use of this TEXTUAL-CONVENTION SHOULD be 1630 accompanied by another object or objects of type 1631 FingerprintValue. 1633 This TEXTUAL-CONVENTION SHOULD NOT be used as a form of 1634 cryptographic verification. Two matching sets of 1635 FingerprintType/FingerprintValue should not be considered 1636 authenticated. These TEXTUAL-CONVENTIONs are only intended for 1637 use as a reference to a stored copy of a longer data source and 1638 the full data sources need to be compared to assure collisions 1639 have not resulted." 1640 SYNTAX OBJECT IDENTIFIER 1642 FingerprintValue ::= TEXTUAL-CONVENTION 1643 STATUS current 1644 DESCRIPTION 1645 "A Fingerprint value that can be used to uniquely reference 1646 other data of potentially arbitrary length. 1648 Objects making use of this TEXTUAL-CONVENTION SHOULD always be 1649 accompanied by a FingerprintType object that dictates the 1650 format of values stored in objects of type FingerprintValue. 1652 This TEXTUAL-CONVENTION SHOULD NOT be used as a form of 1653 cryptographic verification. Two matching sets of 1654 FingerprintType/FingerprintValue should not be considered 1655 authenticated. These TEXTUAL-CONVENTIONs are only intended for 1656 use as a reference to a stored copy of a longer data source and 1657 the full data sources need to be compared to assure collisions 1658 have not resulted." 1659 SYNTAX OCTET STRING 1661 -- The Fingerprint Identifiers Objects 1663 tlstmFingerprintTypes OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1665 tlstmMD5 OBJECT-IDENTITY 1666 STATUS current 1667 DESCRIPTION 1668 "An identifier for the MD5 hashing algorithm to be used with 1669 FingerprintType objects. The resulting value to be placed into 1670 the corresponding FingerprintValue object should be a 1671 full-length MD5 hash (16 octets)." 1672 ::= { tlstmFingerprintTypes 1 } 1674 tlstmSHA1 OBJECT-IDENTITY 1675 STATUS current 1676 DESCRIPTION 1677 "An identifier for the SHA1 hashing algorithm to be used with 1678 FingerprintType objects. The resulting value to be placed into 1679 the corresponding FingerprintValue object should be a 1680 full-length SHA1 hash (20 octets)." 1681 ::= { tlstmFingerprintTypes 2 } 1683 tlstmSHA256 OBJECT-IDENTITY 1684 STATUS current 1685 DESCRIPTION 1686 "An identifier for the SHA256 hashing algorithm to be used with 1687 FingerprintType objects. The resulting value to be placed into 1688 the corresponding FingerprintValue object should be a 1689 full-length SHA256 hash (32 octets)." 1690 ::= { tlstmFingerprintTypes 3 } 1692 -- The tlstmSession Group 1694 tlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1696 tlstmSessionOpens OBJECT-TYPE 1697 SYNTAX Counter32 1698 MAX-ACCESS read-only 1699 STATUS current 1700 DESCRIPTION 1701 "The number of times an openSession() request has been 1702 executed as an (D)TLS client, whether it succeeded or failed." 1703 ::= { tlstmSession 1 } 1705 tlstmSessionCloses OBJECT-TYPE 1706 SYNTAX Counter32 1707 MAX-ACCESS read-only 1708 STATUS current 1709 DESCRIPTION 1710 "The number of times a closeSession() request has been 1711 executed as an (D)TLS client, whether it succeeded or failed." 1712 ::= { tlstmSession 2 } 1714 tlstmSessionOpenErrors OBJECT-TYPE 1715 SYNTAX Counter32 1716 MAX-ACCESS read-only 1717 STATUS current 1718 DESCRIPTION 1719 "The number of times an openSession() request failed to open a 1720 session as a (D)TLS client, for any reason." 1721 ::= { tlstmSession 3 } 1723 tlstmSessionNoAvailableSessions OBJECT-TYPE 1724 SYNTAX Counter32 1725 MAX-ACCESS read-only 1726 STATUS current 1727 DESCRIPTION 1728 "The number of times an outgoing message was dropped because 1729 the session associated with the passed tmStateReference was no 1730 longer (or was never) available." 1731 ::= { tlstmSession 4 } 1733 tlstmSessionInvalidClientCertificates OBJECT-TYPE 1734 SYNTAX Counter32 1735 MAX-ACCESS read-only 1736 STATUS current 1737 DESCRIPTION 1738 "The number of times an incoming session was not established 1739 on an (D)TLS server because the presented client certificate was 1740 invalid. Reasons for invalidation includes, but is not 1741 limited to, cryptographic validation failures and lack of a 1742 suitable mapping row in the tlstmCertToSNTable." 1743 ::= { tlstmSession 5 } 1745 tlstmSessionInvalidServerCertificates OBJECT-TYPE 1746 SYNTAX Counter32 1747 MAX-ACCESS read-only 1748 STATUS current 1749 DESCRIPTION 1750 "The number of times an outgoing session was not established 1751 on an (D)TLS client because the presented server certificate was 1752 invalid. Reasons for invalidation includes, but is not 1753 limited to, cryptographic validation failures and an unexpected 1754 presented certificate identity." 1755 ::= { tlstmSession 6 } 1757 tlstmTLSProtectionErrors OBJECT-TYPE 1758 SYNTAX Counter32 1759 MAX-ACCESS read-only 1760 STATUS current 1761 DESCRIPTION 1762 "The number of times (D)TLS processing resulted in a message 1763 being discarded because it failed its integrity test, 1764 decryption processing or other (D)TLS processing." 1765 ::= { tlstmSession 7 } 1767 -- Configuration Objects 1769 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 3 } 1771 -- Certificate mapping 1773 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1775 tlstmCertToSNCount OBJECT-TYPE 1776 SYNTAX Unsigned32 1777 MAX-ACCESS read-only 1778 STATUS current 1779 DESCRIPTION 1780 "A count of the number of entries in the 1781 tlstmCertToSNTable" 1782 ::= { tlstmCertificateMapping 1 } 1784 tlstmCertToSNTableLastChanged OBJECT-TYPE 1785 SYNTAX TimeStamp 1786 MAX-ACCESS read-only 1787 STATUS current 1788 DESCRIPTION 1789 "The value of sysUpTime.0 when the tlstmCertToSNTable 1790 was last modified through any means, or 0 if it has not been 1791 modified since the command responder was started." 1792 ::= { tlstmCertificateMapping 2 } 1794 tlstmCertToSNTable OBJECT-TYPE 1795 SYNTAX SEQUENCE OF TlstmCertToSNEntry 1796 MAX-ACCESS not-accessible 1797 STATUS current 1798 DESCRIPTION 1799 "A table listing the X.509 certificates known to the entity 1800 and the associated method for determining the SNMPv3 security 1801 name from a certificate. 1803 On an incoming (D)TLS/SNMP connection the client's presented 1804 certificate must be examined and validated based on an 1805 established trusted path from a CA certificate or self-signed 1806 public certificate (e.g. RFC5280). This table provides a 1807 mapping from a validated certificate to a SNMPv3 securityName. 1808 This table does not provide any mechanisms for uploading 1809 trusted certificates and the transfer of any needed trusted 1810 certificates for path validation is expected to occur through 1811 an out-of-band transfer. 1813 Once the authenticity of a certificate has been verified, this 1814 table is consulted to determine the appropriate securityName 1815 to identify with the remote connection. This is done by 1816 considering each active row from this table in prioritized 1817 order according to its tlstmCertToSNID value. Each row's 1818 tlstmCertToSNHashType and tlstmCertToSNHashValue values 1819 determine whether the row is a match for the incoming 1820 connection: 1822 1) If the row's tlstmCertToSNHashType and 1823 tlstmCertToSNHashValue values identify the presented 1824 certificate and the contents of the presented 1825 certificate match a locally cached copy of the 1826 certificate then consider the row as a successful 1827 match. 1829 2) If the row's tlstmCertToSNHashType and 1830 tlstmCertToSNHashValue values identify a locally held 1831 copy of a trusted CA certificate and that CA 1832 certificated was used to validate the presented 1833 certificate then consider the row as a successful 1834 match. 1836 Once a matching row has been found, the tlstmCertToSNMapType 1837 value can be used to determine how the securityName to 1838 associate with the session should be determined. See the 1839 tlstmCertToSNMapType column's DESCRIPTION for details on 1840 determining the securityName value. If it is impossible to 1841 determine the resulting securityName from the row's data 1842 combined with the data presented in the certificate then 1843 additional rows MUST be searched looking for another potential 1844 match. If a resulting securityName mapped from a given row is 1845 not compatible with the needed requirements of a legal 1846 securityName (i.e., VACM imposes a 32-octet-maximum length) 1847 then it must be considered an invalid match and additional 1848 rows MUST be searched looking for another potential match. 1850 Missing values of tlstmCertToSNID are acceptable and 1851 implementations should continue to the next highest numbered 1852 row. E.G., the table may legally contain only two rows with 1853 tlstmCertToSNID values of 10 and 20. 1855 Users are encouraged to make use of certificates with 1856 subjectAltName fields that can be used as securityNames so 1857 that a single root CA certificate can allow all child 1858 certificate's subjectAltName to map directly to a securityName 1859 via a 1:1 transformation. However, this table is flexible to 1860 allow for situations where existing deployed certificate 1861 infrastructures do not provide adequate subjectAltName values 1862 for use as SNMPv3 securityNames. Certificates may also be 1863 mapped to securityNames using the CommonName portion of the 1864 Subject field but usage of the CommonName field is deprecated. 1865 Direct mapping from each individual certificate fingerprint to 1866 a securityName is also possible but requires one entry in the 1867 table per securityName and requires more management operations 1868 to completely configure a device." 1869 ::= { tlstmCertificateMapping 3 } 1871 tlstmCertToSNEntry OBJECT-TYPE 1872 SYNTAX TlstmCertToSNEntry 1873 MAX-ACCESS not-accessible 1874 STATUS current 1875 DESCRIPTION 1876 "A row in the tlstmCertToSNTable that specifies a 1877 mapping for an incoming (D)TLS certificate to a securityName 1878 to use for a connection." 1879 INDEX { tlstmCertToSNID } 1880 ::= { tlstmCertToSNTable 1 } 1882 TlstmCertToSNEntry ::= SEQUENCE { 1883 tlstmCertToSNID Unsigned32, 1884 tlstmCertToSNHashType FingerprintType, 1885 tlstmCertToSNHashValue FingerprintValue, 1886 tlstmCertToSNMapType INTEGER, 1887 tlstmCertToSNSecurityName SnmpAdminString, 1888 tlstmCertToSNSANType INTEGER, 1889 tlstmCertToSNStorageType StorageType, 1890 tlstmCertToSNRowStatus RowStatus 1891 } 1892 tlstmCertToSNID OBJECT-TYPE 1893 SYNTAX Unsigned32 1894 MAX-ACCESS not-accessible 1895 STATUS current 1896 DESCRIPTION 1897 "A unique, prioritized index for a given certificate entry." 1898 ::= { tlstmCertToSNEntry 1 } 1900 tlstmCertToSNHashType OBJECT-TYPE 1901 SYNTAX FingerprintType 1902 MAX-ACCESS read-create 1903 STATUS current 1904 DESCRIPTION 1905 "The hash algorithm to use when applying a hash to a X.509 1906 certificate for purposes of referring to it from the 1907 tlstmCertToSNHashValue column." 1908 DEFVAL { tlstmSHA256 } 1909 ::= { tlstmCertToSNEntry 2 } 1911 tlstmCertToSNHashValue OBJECT-TYPE 1912 SYNTAX FingerprintValue 1913 MAX-ACCESS read-create 1914 STATUS current 1915 DESCRIPTION 1916 "A cryptographic hash of a X.509 certificate. The results of 1917 a successful matching fingerprint is dictated by the 1918 tlstmCertToSNMapType column. A match of the fingerprint MUST 1919 only be considered successful if both the fingerprint type 1920 (tlstmCertToSNMapType) and fingerprint value 1921 (tlstmCertToSNHashValue) columns have been found equal to the 1922 type and value of the certificate being checked." 1923 ::= { tlstmCertToSNEntry 3 } 1925 tlstmCertToSNMapType OBJECT-TYPE 1926 SYNTAX INTEGER { specified(1), bySubjectAltName(2), byCN(3) } 1927 MAX-ACCESS read-create 1928 STATUS current 1929 DESCRIPTION 1930 "The mapping type used to obtain the securityName from the 1931 certificate. The possible values of use and their usage 1932 methods are defined as follows: 1934 specified(1): The securityName that should be used to 1935 associate with the session is directly 1936 specified in the tlstmCertToSNecurityName column 1937 from this table. 1939 bySubjectAltName(2): 1940 The securityName that should be used to 1941 associate with the session should be taken from 1942 the subjectAltName(s) portion of the client's 1943 X.509 certificate. The subjectAltName used MUST 1944 be the first encountered subjectAltName type 1945 indicated by the tlstmCertToSNSANType column. 1946 If no subjectAltName of the given type is found 1947 within the certificate then additional rows in 1948 the tlstmCertToSNTable must be searched. 1950 byCN(3): The securityName that should be used to 1951 associate with the session should be taken from 1952 the CommonName portion of the Subject field from 1953 the client's presented X.509 certificate. 1955 If the resulting mapped value from the subjectAltName 1956 component is not compatible with the needed requirements of a 1957 legal securityName (i.e., VACM imposes a 32-octet-maximum 1958 length) then the next appropriate subjectAltName of the 1959 correct type should be used if available. 1961 If this object is of type bySubjectAltName(2) and no 1962 subjectAltName value can be found that meets the requirements 1963 of this object then any additional rows in the 1964 tlstmCertToSNTable must be searched. 1966 If this object is of type byCN(3) and the CommonName value 1967 does not meet the requirements of this object then any 1968 additional rows in the tlstmCertToSNTable must be searched." 1970 DEFVAL { specified } 1971 ::= { tlstmCertToSNEntry 4 } 1973 tlstmCertToSNSecurityName OBJECT-TYPE 1974 SYNTAX SnmpAdminString (SIZE(0..32)) 1975 MAX-ACCESS read-create 1976 STATUS current 1977 DESCRIPTION 1978 "The securityName that the session should use if the 1979 tlstmCertToSNMapType is set to specified(1), otherwise the 1980 value in this column should be ignored. If 1981 tlstmCertToSNMapType is set to specifed(1) and this column 1982 contains a zero-length string (which is not a legal 1983 securityName value) this row is effectively disabled and the 1984 match will not be considered successful and other rows in the 1985 table will need to be searched." 1986 DEFVAL { "" } 1987 ::= { tlstmCertToSNEntry 5 } 1989 tlstmCertToSNSANType OBJECT-TYPE 1990 SYNTAX INTEGER { any(1), rfc822Name(2), dNSName(3), 1991 ipAddress(4), otherName(5) } 1992 MAX-ACCESS read-create 1993 STATUS current 1994 DESCRIPTION 1995 "Specifies the subjectAltName type that may be used to extract 1996 the securityName from. 1998 The any(1) value indicates the (D)TLS server should use the 1999 first value found for any of the following subjectAltName 2000 value types for the securityName: rfc822Name, dNSName, and 2001 ipAddress. 2003 When multiple types for a given subjectAltName type are 2004 encountered within a certificate the first legally usable 2005 value is the one selected. 2007 Values for type ipAddress(4) are converted to a valid 2008 securityName by: 2010 1) for IPv4 the value is converted into a decimal dotted 2011 quad address (e.g. '192.0.2.1') 2013 2) for IPv6 addresses the value is converted into a 2014 32-character hexadecimal string without any colon 2015 separators. 2017 Values for type otherName(5) are converted to a valid 2018 securityName by using only the decoded value portion of the 2019 OthenName sequence. i.e. the OBJECT IDENTIFIER portion of the 2020 OtherName sequence is not included as part of the resulting 2021 securityName." 2022 DEFVAL { any } 2023 ::= { tlstmCertToSNEntry 6 } 2025 tlstmCertToSNStorageType OBJECT-TYPE 2026 SYNTAX StorageType 2027 MAX-ACCESS read-create 2028 STATUS current 2029 DESCRIPTION 2030 "The storage type for this conceptual row. Conceptual rows 2031 having the value 'permanent' need not allow write-access to 2032 any columnar objects in the row." 2033 DEFVAL { nonVolatile } 2034 ::= { tlstmCertToSNEntry 7 } 2036 tlstmCertToSNRowStatus OBJECT-TYPE 2037 SYNTAX RowStatus 2038 MAX-ACCESS read-create 2039 STATUS current 2040 DESCRIPTION 2041 "The status of this conceptual row. This object may be used 2042 to create or remove rows from this table. 2044 To create a row in this table, a manager must set this object 2045 to either createAndGo(4) or createAndWait(5). 2047 Until instances of all corresponding columns are appropriately 2048 configured, the value of the corresponding instance of the 2049 tlstmParamsRowStatus column is 'notReady'. 2051 In particular, a newly created row cannot be made active until 2052 the corresponding tlstmCertToSNHashType, 2053 tlstmCertToSNHashValue, tlstmCertToSNMapType, 2054 tlstmCertToSNSecurityName, and tlstmCertToSNSANType columns 2055 have been set. 2057 The following objects may not be modified while the 2058 value of this object is active(1): 2059 - tlstmCertToSNHashType 2060 - tlstmCertToSNHashValue 2061 - tlstmCertToSNMapType 2062 - tlstmCertToSNSecurityName 2063 - tlstmCertToSNSANType 2064 An attempt to set these objects while the value of 2065 tlstmParamsRowStatus is active(1) will result in 2066 an inconsistentValue error." 2067 ::= { tlstmCertToSNEntry 8 } 2069 -- Maps securityNames to certificates for use by the SNMP-TARGET-MIB 2071 tlstmParamsCount OBJECT-TYPE 2072 SYNTAX Unsigned32 2073 MAX-ACCESS read-only 2074 STATUS current 2075 DESCRIPTION 2076 "A count of the number of entries in the tlstmParamsTable" 2077 ::= { tlstmCertificateMapping 4 } 2079 tlstmParamsTableLastChanged OBJECT-TYPE 2080 SYNTAX TimeStamp 2081 MAX-ACCESS read-only 2082 STATUS current 2083 DESCRIPTION 2084 "The value of sysUpTime.0 when the tlstmParamsTable 2085 was last modified through any means, or 0 if it has not been 2086 modified since the command responder was started." 2087 ::= { tlstmCertificateMapping 5 } 2089 tlstmParamsTable OBJECT-TYPE 2090 SYNTAX SEQUENCE OF TlstmParamsEntry 2091 MAX-ACCESS not-accessible 2092 STATUS current 2093 DESCRIPTION 2094 "This table extends the SNMP-TARGET-MIB's 2095 snmpTargetParamsTable with an additional (D)TLS client-side 2096 certificate fingerprint identifier to use when establishing 2097 new (D)TLS connections." 2098 ::= { tlstmCertificateMapping 6 } 2100 tlstmParamsEntry OBJECT-TYPE 2101 SYNTAX TlstmParamsEntry 2102 MAX-ACCESS not-accessible 2103 STATUS current 2104 DESCRIPTION 2105 "A conceptual row containing a locally held certificate's hash 2106 type and hash value for a given snmpTargetParamsEntry. The 2107 values in this row should be ignored if the connection that 2108 needs to be established, as indicated by the SNMP-TARGET-MIB 2109 infrastructure, is not a certificate and (D)TLS based 2110 connection. The connection SHOULD NOT be established if the 2111 certificate fingerprint stored in this entry does not point to 2112 a valid locally held certificate or if it points to an usable 2113 certificate (such as might happen when the certificate's 2114 expiration date has been reached)." 2115 INDEX { IMPLIED snmpTargetParamsName } 2116 ::= { tlstmParamsTable 1 } 2118 TlstmParamsEntry ::= SEQUENCE { 2119 tlstmParamsClientHashType FingerprintType, 2120 tlstmParamsClientHashValue FingerprintValue, 2121 tlstmParamsStorageType StorageType, 2122 tlstmParamsRowStatus RowStatus 2123 } 2125 tlstmParamsClientHashType OBJECT-TYPE 2126 SYNTAX FingerprintType 2127 MAX-ACCESS read-create 2128 STATUS current 2129 DESCRIPTION 2130 "The hash algorithm type for the hash stored in the 2131 tlstmParamsClientHash column to identify a locally-held X.509 2132 certificate that should be used when initiating a (D)TLS 2133 connection as a (D)TLS client." 2134 DEFVAL { tlstmSHA256 } 2135 ::= { tlstmParamsEntry 1 } 2137 tlstmParamsClientHashValue OBJECT-TYPE 2138 SYNTAX FingerprintValue 2139 MAX-ACCESS read-create 2140 STATUS current 2141 DESCRIPTION 2142 "A cryptographic hash of a X.509 certificate. This object 2143 should store the hash of a locally held X.509 certificate that 2144 should be used when initiating a (D)TLS connection as a (D)TLS 2145 client." 2146 ::= { tlstmParamsEntry 2 } 2148 tlstmParamsStorageType OBJECT-TYPE 2149 SYNTAX StorageType 2150 MAX-ACCESS read-create 2151 STATUS current 2152 DESCRIPTION 2153 "The storage type for this conceptual row. Conceptual rows 2154 having the value 'permanent' need not allow write-access to 2155 any columnar objects in the row." 2156 DEFVAL { nonVolatile } 2157 ::= { tlstmParamsEntry 3 } 2159 tlstmParamsRowStatus OBJECT-TYPE 2160 SYNTAX RowStatus 2161 MAX-ACCESS read-create 2162 STATUS current 2163 DESCRIPTION 2164 "The status of this conceptual row. This object may be used 2165 to create or remove rows from this table. 2167 To create a row in this table, a manager must set this object 2168 to either createAndGo(4) or createAndWait(5). 2170 Until instances of all corresponding columns are appropriately 2171 configured, the value of the corresponding instance of the 2172 tlstmParamsRowStatus column is 'notReady'. 2174 In particular, a newly created row cannot be made active until 2175 the corresponding tlstmParamsClientHashType and 2176 tlstmParamsClientHashValue columns have been set. 2178 The following objects may not be modified while the 2179 value of this object is active(1): 2180 - tlstmParamsClientHashType 2181 - tlstmParamsClientHashValue 2182 An attempt to set these objects while the value of 2183 tlstmParamsRowStatus is active(1) will result in 2184 an inconsistentValue error. 2186 If this row is deleted it has no effect on the corresponding 2187 row in the targetParamsTable. 2189 If the corresponding row in the targetParamsTable is deleted 2190 then this row must be automatically removed." 2191 ::= { tlstmParamsEntry 4 } 2193 -- Lists expected certificate fingerprints to be presented by a DTLS 2194 -- server 2196 tlstmAddrCount OBJECT-TYPE 2197 SYNTAX Unsigned32 2198 MAX-ACCESS read-only 2199 STATUS current 2200 DESCRIPTION 2201 "A count of the number of entries in the tlstmAddrTable" 2202 ::= { tlstmCertificateMapping 7 } 2204 tlstmAddrTableLastChanged OBJECT-TYPE 2205 SYNTAX TimeStamp 2206 MAX-ACCESS read-only 2207 STATUS current 2208 DESCRIPTION 2209 "The value of sysUpTime.0 when the tlstmAddrTable 2210 was last modified through any means, or 0 if it has not been 2211 modified since the command responder was started." 2212 ::= { tlstmCertificateMapping 8 } 2214 tlstmAddrTable OBJECT-TYPE 2215 SYNTAX SEQUENCE OF TlstmAddrEntry 2216 MAX-ACCESS not-accessible 2217 STATUS current 2218 DESCRIPTION 2219 "This table extends the SNMP-TARGET-MIB's snmpTargetAddrTable 2220 with an expected (D)TLS server-side certificate identifier to 2221 expect when establishing a new (D)TLS connections. If a 2222 matching row in this table exists and the row is active then a 2223 local copy of the certificate matching the fingerprint 2224 identifier should be compared against the certificate being 2225 presented by the server. If the certificate presented by the 2226 server does not match the locally held copy then the 2227 connection MUST NOT be established. If no matching row exists 2228 in this table then the connection SHOULD still proceed if 2229 another certificate validation path algorithm (e.g. RFC5280) 2230 can be followed to a configured trust anchor. " 2231 ::= { tlstmCertificateMapping 9 } 2233 tlstmAddrEntry OBJECT-TYPE 2234 SYNTAX TlstmAddrEntry 2235 MAX-ACCESS not-accessible 2236 STATUS current 2237 DESCRIPTION 2238 "A conceptual row containing a copy of a locally held 2239 certificate's hash type and hash value for a given 2240 snmpTargetAddrEntry. The values in this row should be ignored 2241 if the connection that needs to be established, as indicated 2242 by the SNMP-TARGET-MIB infrastructure, is not a (D)TLS based 2243 connection. If an tlstmAddrEntry exists for a given 2244 snmpTargetAddrEntry then the presented server certificate MUST 2245 match or the connection MUST NOT be established. If a row in 2246 this table does not exist to match a snmpTargetAddrEntry row 2247 then the connection SHOULD still proceed if some other 2248 certificate validation path algorithm (e.g. RFC5280) can be 2249 followed to a configured trust anchor." 2250 INDEX { IMPLIED snmpTargetAddrName } 2251 ::= { tlstmAddrTable 1 } 2253 TlstmAddrEntry ::= SEQUENCE { 2254 tlstmAddrServerHashType FingerprintType, 2255 tlstmAddrServerHashValue FingerprintValue, 2256 tlstmAddrStorageType StorageType, 2257 tlstmAddrRowStatus RowStatus 2258 } 2260 tlstmAddrServerHashType OBJECT-TYPE 2261 SYNTAX FingerprintType 2262 MAX-ACCESS read-create 2263 STATUS current 2264 DESCRIPTION 2265 "The hash algorithm type for the hash stored in the 2266 tlstmAddrServerHash column to identify a local copy of the 2267 public X.509 certificate presented by the TLS server." 2268 DEFVAL { tlstmSHA256 } 2269 ::= { tlstmAddrEntry 1 } 2271 tlstmAddrServerHashValue OBJECT-TYPE 2272 SYNTAX FingerprintValue 2273 MAX-ACCESS read-create 2274 STATUS current 2275 DESCRIPTION 2276 "A cryptographic hash of a public X.509 certificate. This 2277 object should store the hash of a local copy of the public 2278 X.509 certificate that the remote server should present during 2279 the (D)TLS connection setup. The presented certificate and 2280 the locally held copy, referred to by this hash value, MUST 2281 match exactly or the connection MUST NOT be established." 2282 ::= { tlstmAddrEntry 2 } 2284 tlstmAddrStorageType OBJECT-TYPE 2285 SYNTAX StorageType 2286 MAX-ACCESS read-create 2287 STATUS current 2288 DESCRIPTION 2289 "The storage type for this conceptual row. Conceptual rows 2290 having the value 'permanent' need not allow write-access to 2291 any columnar objects in the row." 2292 DEFVAL { nonVolatile } 2293 ::= { tlstmAddrEntry 3 } 2295 tlstmAddrRowStatus OBJECT-TYPE 2296 SYNTAX RowStatus 2297 MAX-ACCESS read-create 2298 STATUS current 2299 DESCRIPTION 2300 "The status of this conceptual row. This object may be used 2301 to create or remove rows from this table. 2303 To create a row in this table, a manager must 2304 set this object to either createAndGo(4) or 2305 createAndWait(5). 2307 Until instances of all corresponding columns are 2308 appropriately configured, the value of the 2309 corresponding instance of the tlstmAddrRowStatus 2310 column is 'notReady'. 2312 In particular, a newly created row cannot be made active until 2313 the corresponding tlstmAddrServerHashType, and 2314 tlstmAddrServerHashValue columns have been set. 2316 The following objects may not be modified while the 2317 value of this object is active(1): 2318 - tlstmAddrServerHashType 2319 - tlstmAddrServerHashValue 2321 An attempt to set these objects while the value of 2322 tlstmAddrRowStatus is active(1) will result in 2323 an inconsistentValue error. 2325 If this row is deleted it has no effect on the corresponding 2326 row in the targetAddrTable. 2328 If the corresponding row in the targetAddrTable is deleted 2329 then this row must be automatically removed." 2330 ::= { tlstmAddrEntry 4 } 2332 -- ************************************************ 2333 -- tlstmMIB - Conformance Information 2334 -- ************************************************ 2336 tlstmCompliances OBJECT IDENTIFIER ::= { tlstmConformance 1 } 2338 tlstmGroups OBJECT IDENTIFIER ::= { tlstmConformance 2 } 2340 -- ************************************************ 2341 -- Compliance statements 2342 -- ************************************************ 2344 tlstmCompliance MODULE-COMPLIANCE 2345 STATUS current 2346 DESCRIPTION 2347 "The compliance statement for SNMP engines that support the 2348 TLSTM-MIB" 2349 MODULE 2350 MANDATORY-GROUPS { tlstmStatsGroup, 2351 tlstmIncomingGroup, tlstmOutgoingGroup } 2352 ::= { tlstmCompliances 1 } 2354 -- ************************************************ 2355 -- Units of conformance 2356 -- ************************************************ 2357 tlstmStatsGroup OBJECT-GROUP 2358 OBJECTS { 2359 tlstmSessionOpens, 2360 tlstmSessionCloses, 2361 tlstmSessionOpenErrors, 2362 tlstmSessionNoAvailableSessions, 2363 tlstmSessionInvalidClientCertificates, 2364 tlstmSessionInvalidServerCertificates, 2365 tlstmTLSProtectionErrors 2367 } 2368 STATUS current 2369 DESCRIPTION 2370 "A collection of objects for maintaining 2371 statistical information of an SNMP engine which 2372 implements the SNMP TLS Transport Model." 2373 ::= { tlstmGroups 1 } 2375 tlstmIncomingGroup OBJECT-GROUP 2376 OBJECTS { 2377 tlstmCertToSNCount, 2378 tlstmCertToSNTableLastChanged, 2379 tlstmCertToSNHashType, 2380 tlstmCertToSNHashValue, 2381 tlstmCertToSNMapType, 2382 tlstmCertToSNSecurityName, 2383 tlstmCertToSNSANType, 2384 tlstmCertToSNStorageType, 2385 tlstmCertToSNRowStatus 2386 } 2387 STATUS current 2388 DESCRIPTION 2389 "A collection of objects for maintaining 2390 incoming connection certificate mappings to 2391 securityNames of an SNMP engine which implements the 2392 SNMP TLS Transport Model." 2393 ::= { tlstmGroups 2 } 2395 tlstmOutgoingGroup OBJECT-GROUP 2396 OBJECTS { 2397 tlstmParamsCount, 2398 tlstmParamsTableLastChanged, 2399 tlstmParamsClientHashType, 2400 tlstmParamsClientHashValue, 2401 tlstmParamsStorageType, 2402 tlstmParamsRowStatus, 2403 tlstmAddrCount, 2404 tlstmAddrTableLastChanged, 2405 tlstmAddrServerHashType, 2406 tlstmAddrServerHashValue, 2407 tlstmAddrStorageType, 2408 tlstmAddrRowStatus 2409 } 2410 STATUS current 2411 DESCRIPTION 2412 "A collection of objects for maintaining 2413 outgoing connection certificates to use when opening 2414 connections as a result of SNMP-TARGET-MIB settings." 2416 ::= { tlstmGroups 3 } 2418 END 2420 8. Operational Considerations 2422 This section discusses various operational aspects of the solution 2424 8.1. Sessions 2426 A session is discussed throughout this document as meaning a security 2427 association between the (D)TLS client and the (D)TLS server. State 2428 information for the sessions are maintained in each TLSTM and this 2429 information is created and destroyed as sessions are opened and 2430 closed. Because of the connectionless nature of UDP, a "broken" 2431 session, one side up one side down, could result if one side of a 2432 session is brought down abruptly (i.e., reboot, power outage, etc.). 2433 Whenever possible, implementations SHOULD provide graceful session 2434 termination through the use of disconnect messages. Implementations 2435 SHOULD also have a system in place for dealing with "broken" 2436 sessions. Implementations SHOULD support the session resumption 2437 feature of TLS. 2439 To simplify session management it is RECOMMENDED that implementations 2440 utilize two separate ports, one for Notification sessions and one for 2441 Command sessions. If this implementation recommendation is followed, 2442 (D)TLS clients will always send REQUEST messages and (D)TLS servers 2443 will always send RESPONSE messages. With this assertion, 2444 implementations may be able to simplify "broken" session handling, 2445 session resumption, and other aspects of session management such as 2446 guaranteeing that Request- Response pairs use the same session. 2448 Implementations SHOULD limit the lifetime of established sessions 2449 depending on the algorithms used for generation of the master session 2450 secret, the privacy and integrity algorithms used to protect 2451 messages, the environment of the session, the amount of data 2452 transferred, and the sensitivity of the data. 2454 8.2. Notification Receiver Credential Selection 2456 When an SNMP engine needs to establish an outgoing session for 2457 notifications, the snmpTargetParamsTable includes an entry for the 2458 snmpTargetParamsSecurityName of the target. However, the receiving 2459 SNMP engine (Server) does not know which (D)TLS certificate to offer 2460 to the Client so that the tmSecurityName identity-authentication will 2461 be successful. The best solution would be to maintain a one-to-one 2462 mapping between certificates and incoming ports for notification 2463 receivers, although other implementation dependent mechanisms may be 2464 used instead. This can be handled at the Notification Originator by 2465 configuring the snmpTargetAddrTable (snmpTargetAddrTDomain and 2466 snmpTargetAddrTAddress) and then requiring the receiving SNMP engine 2467 to monitor multiple incoming static ports based on which principals 2468 are capable of receiving notifications. Implementations MAY also 2469 choose to designate a single Notification Receiver Principal to 2470 receive all incoming TRAPS and INFORMS. 2472 8.3. contextEngineID Discovery 2474 Because most Command Responders have contextEngineIDs that are 2475 identical to the USM securityEngineID, the USM provides Command 2476 Generators with the ability to discover a default contextEngineID to 2477 use. Because the TLS Transport Model does not make use of a 2478 discoverable securityEngineID like the USM does, it may be difficult 2479 for Command Generators to discover a suitable default 2480 contextEngineID. Implementations should consider offering another 2481 engineID discovery mechanism to continue providing Command Generators 2482 with a contextEngineID discovery mechanism. A recommended discovery 2483 solution is documented in [RFC5343]. 2485 9. Security Considerations 2487 This document describes a transport model that permits SNMP to 2488 utilize (D)TLS security services. The security threats and how the 2489 (D)TLS transport model mitigates these threats are covered in detail 2490 throughout this document. Security considerations for DTLS are 2491 covered in [RFC4347] and security considerations for TLS are 2492 described in Section 11 and Appendices D, E, and F of TLS 1.2 2493 [RFC5246]. DTLS adds to the security considerations of TLS only 2494 because it is more vulnerable to denial of service attacks. A random 2495 cookie exchange was added to the handshake to prevent anonymous 2496 denial of service attacks. RFC 4347 recommends that the cookie 2497 exchange is utilized for all handshakes and therefore it is 2498 RECOMMENDED that implementers also support this cookie exchange. 2500 9.1. Certificates, Authentication, and Authorization 2502 Implementations are responsible for providing a security certificate 2503 configuration installation . Implementations SHOULD support 2504 certificate revocation lists and expiration of certificates or other 2505 access control mechanisms. 2507 (D)TLS provides for both authentication of the identity of the (D)TLS 2508 server and authentication of the identity of the (D)TLS client. 2509 Access to MIB objects for the authenticated principal MUST be 2510 enforced by an access control subsystem (e.g. the VACM). 2512 Authentication of the Command Generator principal's identity is 2513 important for use with the SNMP access control subsystem to ensure 2514 that only authorized principals have access to potentially sensitive 2515 data. The authenticated identity of the Command Generator 2516 principal's certificate is mapped to an SNMP model-independent 2517 securityName for use with SNMP access control. 2519 Furthermore, the (D)TLS handshake only provides assurance that the 2520 certificate of the authenticated identity has been signed by an 2521 configured accepted Certificate Authority. (D)TLS has no way to 2522 further authorize or reject access based on the authenticated 2523 identity. An Access Control Model (such as the VACM) provides access 2524 control and authorization of a Command Generator's requests to a 2525 Command Responder and a Notification Responder's authorization to 2526 receive Notifications from a Notification Originator. However to 2527 avoid man-in-the-middle attacks both ends of the (D)TLS based 2528 connection MUST check the certificate presented by the other side 2529 against what was expected. For example, Command Generators must 2530 check that the Command Responder presented and authenticated itself 2531 with a X.509 certificate that was expected. Not doing so would allow 2532 an impostor, at a minimum, to present false data, receive sensitive 2533 information and/or provide a false-positive belief that configuration 2534 was actually received and acted upon. Authenticating and verifying 2535 the identity of the (D)TLS server and the (D)TLS client for all 2536 operations ensures the authenticity of the SNMP engine that provides 2537 MIB data. 2539 The instructions found in the DESCRIPTION clause of the 2540 tlstmCertToSNTable object must be followed exactly. Specifically, it 2541 is important that if a row matching a certificate or a certificate's 2542 issuer is found but the translation to a securityName using the row 2543 fails that the lookup process stops and no further rows are 2544 consulted. It is also important that the rows of the table be search 2545 in order starting with the row containing the lowest numbered 2546 tlstmCertToSNID value. 2548 9.2. Use with SNMPv1/SNMPv2c Messages 2550 The SNMPv1 and SNMPv2c message processing described in RFC3484 (BCP 2551 74) [RFC3584] always selects the SNMPv1(1) Security Model for an 2552 SNMPv1 message, or the SNMPv2c(2) Security Model for an SNMPv2c 2553 message. When running SNMPv1/SNMPv2c over a secure transport like 2554 the TLS Transport Model, the securityName and securityLevel used for 2555 access control decisions are then derived from the community string, 2556 not the authenticated identity and securityLevel provided by the TLS 2557 Transport Model. 2559 9.3. MIB Module Security 2561 There are a number of management objects defined in this MIB module 2562 with a MAX-ACCESS clause of read-write and/or read-create. Such 2563 objects may be considered sensitive or vulnerable in some network 2564 environments. The support for SET operations in a non-secure 2565 environment without proper protection can have a negative effect on 2566 network operations. These are the tables and objects and their 2567 sensitivity/vulnerability: 2569 o The tlstmParamsTable can be used to change the outgoing X.509 2570 certificate used to establish a (D)TLS connection. Modification 2571 to objects in this table need to be adequately authenticated since 2572 modification to values in this table will have profound impacts to 2573 the security of outbound connections from the device. Since 2574 knowledge of authorization rules and certificate usage mechanisms 2575 may be considered sensitive, protection from disclosure of the 2576 SNMP traffic via encryption is also highly recommended. 2578 o The tlstmAddrTable can be used to change the expectations of the 2579 certificates presented by a remote (D)TLS server. Modification to 2580 objects in this table need to be adequately authenticated since 2581 modification to values in this table will have profound impacts to 2582 the security of outbound connections from the device. Since 2583 knowledge of authorization rules and certificate usage mechanisms 2584 may be considered sensitive, protection from disclosure of the 2585 SNMP traffic via encryption is also highly recommended. 2587 o The tlstmCertToSNTable is used to specify the mapping of incoming 2588 X.509 certificates to SNMPv3 securityNames. Modification to 2589 objects in this table need to be adequately authenticated since 2590 modification to values in this table will have profound impacts to 2591 the security of incoming connections to the device. Since 2592 knowledge of authorization rules and certificate usage mechanisms 2593 may be considered sensitive, protection from disclosure of the 2594 SNMP traffic via encryption is also highly recommended. 2596 Some of the readable objects in this MIB module (i.e., objects with a 2597 MAX-ACCESS other than not-accessible) may be considered sensitive or 2598 vulnerable in some network environments. It is thus important to 2599 control even GET and/or NOTIFY access to these objects and possibly 2600 to even encrypt the values of these objects when sending them over 2601 the network via SNMP. These are the tables and objects and their 2602 sensitivity/vulnerability: 2604 o This MIB contains a collection of counters that monitor the (D)TLS 2605 connections being established with a device. Since knowledge of 2606 connection and certificate usage mechanisms may be considered 2607 sensitive, protection from disclosure of the SNMP traffic via 2608 encryption is also highly recommended. 2610 SNMP versions prior to SNMPv3 did not include adequate security. 2611 Even if the network itself is secure (for example by using IPsec), 2612 even then, there is no control as to who on the secure network is 2613 allowed to access and GET/SET (read/change/create/delete) the objects 2614 in this MIB module. 2616 It is RECOMMENDED that implementers consider the security features as 2617 provided by the SNMPv3 framework (see [RFC3410], section 8), 2618 including full support for the SNMPv3 cryptographic mechanisms (for 2619 authentication and privacy). 2621 Further, deployment of SNMP versions prior to SNMPv3 is NOT 2622 RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to 2623 enable cryptographic security. It is then a customer/operator 2624 responsibility to ensure that the SNMP entity giving access to an 2625 instance of this MIB module is properly configured to give access to 2626 the objects only to those principals (users) that have legitimate 2627 rights to indeed GET or SET (change/create/delete) them. 2629 10. IANA Considerations 2631 IANA is requested to assign: 2633 1. a TCP port number in the range 1..1023 in the 2634 http://www.iana.org/assignments/port-numbers registry which will 2635 be the default port for SNMP command messages over a TLS 2636 Transport Model as defined in this document, 2638 2. a TCP port number in the range 1..1023 in the 2639 http://www.iana.org/assignments/port-numbers registry which will 2640 be the default port for SNMP notification messages over a TLS 2641 Transport Model as defined in this document, 2643 3. a UDP port number in the range 1..1023 in the 2644 http://www.iana.org/assignments/port-numbers registry which will 2645 be the default port for SNMP command messages over a DTLS/UDP 2646 connection as defined in this document, 2648 4. a UDP port number in the range 1..1023 in the 2649 http://www.iana.org/assignments/port-numbers registry which will 2650 be the default port for SNMP notification messages over a DTLS/ 2651 UDP connection as defined in this document, 2653 5. a SCTP port number in the range 1..1023 in the 2654 http://www.iana.org/assignments/port-numbers registry which will 2655 be the default port for SNMP command messages over a DTLS/SCTP 2656 connection as defined in this document, 2658 6. a SCTP port number in the range 1..1023 in the 2659 http://www.iana.org/assignments/port-numbers registry which will 2660 be the default port for SNMP notification messages over a DTLS/ 2661 SCTP connection as defined in this document, 2663 7. an SMI number under snmpDomains for the snmpTLSDomain object 2664 identifier, 2666 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2667 identifier, 2669 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2670 object identifier, 2672 10. a SMI number under snmpModules, for the MIB module in this 2673 document, 2675 11. "tls" as the corresponding prefix for the snmpTLSDomain in the 2676 SNMP Transport Model registry, 2678 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2679 the SNMP Transport Model registry, 2681 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2682 the SNMP Transport Model registry; 2684 14. Editor's note: this section should be replaced with appropriate 2685 descriptive assignment text after IANA assignments are made and 2686 prior to publication. 2688 11. Acknowledgements 2690 This document closely follows and copies the Secure Shell Transport 2691 Model for SNMP defined by David Harrington and Joseph Salowey in 2692 [I-D.ietf-isms-secshell]. 2694 This document was reviewed by the following people who helped provide 2695 useful comments: David Harrington, Alan Luchuk, Ray Purvis. 2697 This work was supported in part by the United States Department of 2698 Defense. Large portions of this document are based on work by 2699 General Dynamics C4 Systems and the following individuals: Brian 2700 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2701 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2702 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2704 12. References 2706 12.1. Normative References 2708 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2709 Requirement Levels", BCP 14, RFC 2119, March 1997. 2711 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2712 Schoenwaelder, Ed., "Structure of Management Information 2713 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2715 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2716 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2717 STD 58, RFC 2579, April 1999. 2719 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2720 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2721 April 1999. 2723 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2724 Architecture for Describing Simple Network Management 2725 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2726 December 2002. 2728 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2729 Management Protocol (SNMP) Applications", STD 62, 2730 RFC 3413, December 2002. 2732 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2733 (USM) for version 3 of the Simple Network Management 2734 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2736 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2737 Access Control Model (VACM) for the Simple Network 2738 Management Protocol (SNMP)", STD 62, RFC 3415, 2739 December 2002. 2741 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2742 Simple Network Management Protocol (SNMP)", STD 62, 2743 RFC 3418, December 2002. 2745 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2746 "Coexistence between Version 1, Version 2, and Version 3 2747 of the Internet-standard Network Management Framework", 2748 BCP 74, RFC 3584, August 2003. 2750 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2751 Security", RFC 4347, April 2006. 2753 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2754 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2756 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2757 Housley, R., and W. Polk, "Internet X.509 Public Key 2758 Infrastructure Certificate and Certificate Revocation List 2759 (CRL) Profile", RFC 5280, May 2008. 2761 [I-D.ietf-isms-transport-security-model] 2762 Harington, D., "Transport Security Model for SNMP". 2764 [I-D.ietf-isms-tmsm] 2765 Harington, D. and J. Schoenwaelder, "Transport Subsystem 2766 for the Simple Network Management Protocol (SNMP)". 2768 12.2. Informative References 2770 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2771 Protocol", RFC 2522, March 1999. 2773 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2774 "Introduction and Applicability Statements for Internet- 2775 Standard Management Framework", RFC 3410, December 2002. 2777 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 2778 December 2005. 2780 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 2781 RFC 4303, December 2005. 2783 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2784 RFC 4306, December 2005. 2786 [I-D.ietf-isms-secshell] 2787 Harington, D. and J. Salowey, "Secure Shell Transport 2788 Model for SNMP". 2790 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2791 (SNMP) Context EngineID Discovery". 2793 [I-D.saintandre-tls-server-id-check] 2794 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2795 "Best Practices for Checking of Server Identities in the 2796 Context of Transport Layer Security (TLS)". 2798 [AES] National Institute of Standards, "Specification for the 2799 Advanced Encryption Standard (AES)". 2801 [DES] National Institute of Standards, "American National 2802 Standard for Information Systems-Data Link Encryption". 2804 [DSS] National Institute of Standards, "Digital Signature 2805 Standard". 2807 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2808 Obtaining Digital Signatures and Public-Key 2809 Cryptosystems". 2811 [x509] Rivest, R., Shamir, A., and L. M. Adleman, "A Method for 2812 Obtaining Digital Signatures and Public-Key 2813 Cryptosystems". 2815 Appendix A. (D)TLS Overview 2817 The (D)TLS protocol is composed of two layers: the (D)TLS Record 2818 Protocol and the (D)TLS Handshake Protocol. The following 2819 subsections provide an overview of these two layers. Please refer to 2820 [RFC4347] for a complete description of the protocol. 2822 A.1. The (D)TLS Record Protocol 2824 At the lowest layer, layered on top of the transport control protocol 2825 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 2826 Record Protocol. 2828 The (D)TLS Record Protocol provides security that has three basic 2829 properties: 2831 o The session can be confidential. Symmetric cryptography is used 2832 for data encryption (e.g., AES [AES], DES [DES] etc.). The keys 2833 for this symmetric encryption are generated uniquely for each 2834 session and are based on a secret negotiated by another protocol 2835 (such as the (D)TLS Handshake Protocol). The Record Protocol can 2836 also be used without encryption. 2838 o Messages can have data integrity. Message transport includes a 2839 message integrity check using a keyed MAC. Secure hash functions 2840 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 2841 Protocol can operate without a MAC, but is generally only used in 2842 this mode while another protocol is using the Record Protocol as a 2843 transport for negotiating security parameters. 2845 o Messages are protected against replay. (D)TLS uses explicit 2846 sequence numbers and integrity checks. DTLS uses a sliding window 2847 to protect against replay of messages within a session. 2849 (D)TLS also provides protection against replay of entire sessions. 2850 In a properly-implemented keying material exchange, both sides will 2851 generate new random numbers for each exchange. This results in 2852 different encryption and integrity keys for every session. 2854 A.2. The (D)TLS Handshake Protocol 2856 The (D)TLS Record Protocol is used for encapsulation of various 2857 higher-level protocols. One such encapsulated protocol, the (D)TLS 2858 Handshake Protocol, allows the server and client to authenticate each 2859 other and to negotiate an integrity algorithm, an encryption 2860 algorithm and cryptographic keys before the application protocol 2861 transmits or receives its first octet of data. Only the (D)TLS 2862 client can initiate the handshake protocol. The (D)TLS Handshake 2863 Protocol provides security that has three basic properties: 2865 o The peer's identity can be authenticated using asymmetric (public 2866 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 2867 authentication can be made optional, but is generally required by 2868 at least one of the peers. 2870 (D)TLS supports three authentication modes: authentication of both 2871 the server and the client, server authentication with an 2872 unauthenticated client, and total anonymity. For authentication 2873 of both entities, each entity provides a valid certificate chain 2874 leading to an acceptable certificate authority. Each entity is 2875 responsible for verifying that the other's certificate is valid 2876 and has not expired or been revoked. See 2877 [I-D.saintandre-tls-server-id-check] for further details on 2878 standardized processing when checking Server certificate 2879 identities. 2881 o The negotiation of a shared secret is secure: the negotiated 2882 secret is unavailable to eavesdroppers, and for any authenticated 2883 handshake the secret cannot be obtained, even by an attacker who 2884 can place himself in the middle of the session. 2886 o The negotiation is not vulnerable to malicious modification: it is 2887 infeasible for an attacker to modify negotiation communication 2888 without being detected by the parties to the communication. 2890 o DTLS uses a stateless cookie exchange to protect against anonymous 2891 denial of service attacks and has retransmission timers, sequence 2892 numbers, and counters to handle message loss, reordering, and 2893 fragmentation. 2895 Appendix B. PKIX Certificate Infrastructure 2897 Users of a public key from a PKIX / X.509 certificate can be be 2898 confident that the associated private key is owned by the correct 2899 remote subject (person or system) with which an encryption or digital 2900 signature mechanism will be used. This confidence is obtained 2901 through the use of public key certificates, which are data structures 2902 that bind public key values to subjects. The binding is asserted by 2903 having a trusted CA digitally sign each certificate. The CA may base 2904 this assertion upon technical means (i.e., proof of possession 2905 through a challenge- response protocol), presentation of the private 2906 key, or on an assertion by the subject. A certificate has a limited 2907 valid lifetime which is indicated in its signed contents. Because a 2908 certificate's signature and timeliness can be independently checked 2909 by a certificate-using client, certificates can be distributed via 2910 untrusted communications and server systems, and can be cached in 2911 unsecured storage in certificate-using systems. 2913 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8, which was 2914 first published in 1988 as part of the X.500 Directory 2915 recommendations, defines a standard certificate format [x509] which 2916 is a certificate which binds a subject (principal) to a public key 2917 value. This was later further documented in [RFC5280]. 2919 A X.509 certificate is a sequence of three required fields: 2921 tbsCertificate: The field contains the names of the subject and 2922 issuer, a public key associated with the subject, a validity 2923 period, and other associated information. This field may also 2924 contain extension components. 2926 signatureAlgorithm: The signatureAlgorithm field contains the 2927 identifier for the cryptographic algorithm used by the certificate 2928 authority (CA) to sign this certificate. 2930 signatureValue: The signatureValue field contains a digital 2931 signature computed upon the ASN.1 DER encoded tbsCertificate 2932 field. The ASN.1 DER encoded tbsCertificate is used as the input 2933 to the signature function. This signature value is then ASN.1 DER 2934 encoded as a BIT STRING and included in the Certificate's 2935 signature field. By generating this signature, a CA certifies the 2936 validity of the information in the tbsCertificate field. In 2937 particular, the CA certifies the binding between the public key 2938 material and the subject of the certificate. 2940 The basic X.509 authentication procedure is as follows: A system is 2941 initialized with a number of root certificates that contain the 2942 public keys of a number of trusted CAs. When a system receives a 2943 X.509 certificate, signed by one of those CAs, the certificate has to 2944 be verified. It first checks the signatureValue field by using the 2945 public key of the corresponding trusted CA. Then it compares the 2946 decrypted information with a digest of the tbsCertificate field. If 2947 they match, then the subject in the tbsCertificate field is 2948 authenticated. 2950 Appendix C. Target and Notificaton Configuration Example 2952 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2953 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2954 daunting task without an example to follow. The following section 2955 describes an example of what pieces must be in place to accomplish 2956 this configuration. 2958 The isAccessAllowed() ASI requires configuration to exist in the 2959 following SNMP-VIEW-BASED-ACM-MIB tables: 2961 vacmSecurityToGroupTable 2962 vacmAccessTable 2963 vacmViewTreeFamilyTable 2965 The only table that needs to be discussed as particularly different 2966 here is the vacmSecurityToGroupTable. This table is indexed by both 2967 the SNMPv3 security model and the security name. The security model, 2968 when TLSTM is in use, should be set to the value of XXX corresponding 2969 to the TSM [I-D.ietf-isms-transport-security-model]. An example 2970 vacmSecurityToGroupTable row might be filled out as follows (using a 2971 single SNMP SET request): 2973 Note to RFC editor: replace XXX in the previous paragraph above with 2974 the actual IANA-assigned number for the TSM security model and remove 2975 this note. 2977 vacmSecurityModel = XXX (TSM) 2978 vacmSecurityName = "blueberry" 2979 vacmGroupaName = "administrators" 2980 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2981 vacmSecurityToGroupStatus = 4 (createAndGo) 2983 Note to RFC editor: replace XXX in the vacmSecurityModel line above 2984 with the actual IANA-assigned number for the TSM security model and 2985 remove this note. 2987 This example will assume that the "administrators" group has been 2988 given proper permissions via rows in the vacmAccessTable and 2989 vacmViewTreeFamilyTable. 2991 Depending on whether this VACM configuration is for a Command 2992 Responder or a Command Generator the security name "blueberry" will 2993 come from a few different locations. 2995 For Notification Generator's performing authorization checks, the 2996 server's certificate must be verified against the expected 2997 certificate before proceeding to send the notification. The 2998 securityName be set by the SNMP-TARGET-MIB's 2999 snmpTargetParamsSecurityName column or other configuration mechanism 3000 and the certificate to use would be taken from the appropriate entry 3001 in the tlstmParamsTable. The tlstmParamsTable augments the SNMP- 3002 TARGET-MIB's snmpTargetParamsTable with client-side certificate 3003 information. 3005 For Command Responder applications, the vacmSecurityName "blueberry" 3006 value is a value that needs to come from an incoming (D)TLS session. 3007 The mapping from a recevied (D)TLS client certificate to a 3008 securityName is done with the tlstmCertToSNTable. The certificates 3009 must be loaded into the device so that a tlstmCertToSNEntry may refer 3010 to it. As an example, consider the following entry which will 3011 provide a mapping from a X.509's hash fingerprint directly to the 3012 "blueberry" securityName: 3014 tlstmCertToSNID = 1 (chosen by ordering preference) 3015 tlstmCertToSNHashType = tlstmSHA256 3016 tlstmCertToSNHashValue = (appropriate sha256 fingerprint) 3017 tlstmCertToSNMapType = specified(1) 3018 tlstmCertToSNSecurityName = "blueberry" 3019 tlstmCertToSNStorageType = 3 (nonVolatile) 3020 tlstmCertToSNRowStatus = 4 (createAndGo) 3022 The above is an example of how to map a particular certificate to a 3023 particular securityName. It is recommended that users make use of 3024 direct subjectAltName or CommonName mappings where possible since it 3025 will provide a more scalable approach to certificate management. 3026 This entry provides an example of using a subjectAltName mapping: 3028 tlstmCertToSNID = 1 (chosen by ordering preference) 3029 tlstmCertToSNHashType = tlstmSHA256 3030 tlstmCertToSNHashValue = (appropriate sha256 fingerprint) 3031 tlstmCertToSNMapType = bySubjectAltName(2) 3032 tlstmCertToSNSANType = 1 (any) 3033 tlstmCertToSNStorageType = 3 (nonVolatile) 3034 tlstmCertToSNRowStatus = 4 (createAndGo) 3036 The above entry indicates the subjectAltName field for certificates 3037 created by an Issuing certificate with a corresponding hash type and 3038 value will be trusted to always produce common names that are 3039 directly 1 to 1 mappable into SNMPv3 securityNames. This type of 3040 configuration should only be used when the certificate authorities 3041 naming conventions are carefully controlled. 3043 For the example, if the incoming (D)TLS client provided certificate 3044 contained a subjectAltName where the first listed subjectAltName in 3045 the extension is the rfc822Name of "blueberry" and the certificate 3046 was signed by a certificate matching the tlstmCertToSNHashType and 3047 tlstmCertToSNHashValue values above and the CA's certificate was 3048 properly installed on the device then the string "blueberry" would be 3049 used as the securityName for the session. 3051 Author's Address 3053 Wes Hardaker 3054 Sparta, Inc. 3055 P.O. Box 382 3056 Davis, CA 95617 3057 US 3059 Phone: +1 530 792 1913 3060 Email: ietf@hardakers.net