idnits 2.17.00 (12 Aug 2021) /tmp/idnits42893/draft-hardaker-isms-dtls-tm-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2712. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2723. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2730. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2736. ** The document seems to lack an RFC 3978 Section 5.4 (updated by RFC 4748) Copyright Line. 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: ---------------------------------------------------------------------------- == Line 400 has weird spacing: '...patcher v ...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 10, 2008) is 4909 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) == Outdated reference: draft-ietf-isms-transport-security-model has been published as RFC 5591 == Outdated reference: draft-ietf-isms-tmsm has been published as RFC 5590 -- Obsolete informational reference (is this intentional?): RFC 4306 (Obsoleted by RFC 5996) == Outdated reference: draft-ietf-isms-secshell has been published as RFC 5592 Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 8 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: Informational December 10, 2008 5 Expires: June 13, 2009 7 Datagram Transport Layer Security Transport Model for SNMP 8 draft-hardaker-isms-dtls-tm-02.txt 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on June 13, 2009. 35 Abstract 37 This document describes a Transport Model for the Simple Network 38 Management Protocol (SNMP), that uses the Datagram Transport Layer 39 Security (DTLS) protocol. The DTLS protocol provides authentication 40 and privacy services for SNMP applications. This document describes 41 how the DTLS Transport Model (DTLSTM) implements the needed features 42 of a SNMP Transport Subsystem to make this protection possible in an 43 interoperable way. 45 This transport model is designed to meet the security and operational 46 needs of network administrators, operate in environments where a 47 connectionless (UDP) transport is preferred, and integrates well into 48 existing public keying infrastructures. 50 This document also defines a portion of the Management Information 51 Base (MIB) for monitoring and managing the DTLS Transport Model for 52 SNMP. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Requirements Terminology . . . . . . . . . . . . . . . . . 6 58 1.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 59 2. The Datagram Transport Layer Security Protocol . . . . . . . . 6 60 2.1. The DTLS Record Protocol . . . . . . . . . . . . . . . . . 7 61 2.2. The DTLS Handshake Protocol . . . . . . . . . . . . . . . 7 62 3. How the DTLSTM fits into the Transport Subsystem . . . . . . . 8 63 3.1. Security Capabilities of this Model . . . . . . . . . . . 10 64 3.1.1. Threats . . . . . . . . . . . . . . . . . . . . . . . 10 65 3.1.2. Message Protection . . . . . . . . . . . . . . . . . . 12 66 3.1.3. DTLS Sessions . . . . . . . . . . . . . . . . . . . . 13 67 3.2. Security Parameter Passing . . . . . . . . . . . . . . . . 14 68 3.3. Notifications and Proxy . . . . . . . . . . . . . . . . . 14 69 4. Elements of the Model . . . . . . . . . . . . . . . . . . . . 15 70 4.1. Certificates . . . . . . . . . . . . . . . . . . . . . . . 15 71 4.1.1. The Certificate Infrastructure . . . . . . . . . . . . 15 72 4.1.2. Provisioning for the Certificate . . . . . . . . . . . 16 73 4.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 4.3. SNMP Services . . . . . . . . . . . . . . . . . . . . . . 17 75 4.3.1. SNMP Services for an Outgoing Message . . . . . . . . 18 76 4.3.2. SNMP Services for an Incoming Message . . . . . . . . 19 77 4.4. DTLS Services . . . . . . . . . . . . . . . . . . . . . . 19 78 4.4.1. Services for Establishing a Session . . . . . . . . . 20 79 4.4.2. DTLS Services for an Incoming Message . . . . . . . . 21 80 4.4.3. DTLS Services for an Outgoing Message . . . . . . . . 22 81 4.5. Cached Information and References . . . . . . . . . . . . 22 82 4.5.1. securityStateReference . . . . . . . . . . . . . . . . 23 83 4.5.2. tmStateReference . . . . . . . . . . . . . . . . . . . 23 84 4.5.2.1. Transport information . . . . . . . . . . . . . . 24 85 4.5.2.2. securityName . . . . . . . . . . . . . . . . . . . 24 86 4.5.2.3. securityLevel . . . . . . . . . . . . . . . . . . 25 87 4.5.2.4. Session Information . . . . . . . . . . . . . . . 25 88 4.5.3. DTLS Transport Model Cached Information . . . . . . . 26 89 4.5.3.1. Transport Information . . . . . . . . . . . . . . 26 90 4.5.3.2. tmRequestedSecurityLevel . . . . . . . . . . . . . 27 91 4.5.3.3. tmSecurityLevel . . . . . . . . . . . . . . . . . 27 92 4.5.3.4. tmSecurityName . . . . . . . . . . . . . . . . . . 27 93 4.5.4. Transport Model LCD . . . . . . . . . . . . . . . . . 27 94 5. Elements of Procedure . . . . . . . . . . . . . . . . . . . . 28 95 5.1. Procedures for an Incoming Message . . . . . . . . . . . . 28 96 5.1.1. DTLS Processing for Incoming Messages . . . . . . . . 28 97 5.1.2. Transport Processing for Incoming Messages . . . . . . 30 98 5.2. Procedures for an Outgoing Message . . . . . . . . . . . . 31 99 5.3. Establishing a Session . . . . . . . . . . . . . . . . . . 32 100 5.4. Closing a Session . . . . . . . . . . . . . . . . . . . . 34 101 6. MIB Module Overview . . . . . . . . . . . . . . . . . . . . . 35 102 6.1. Structure of the MIB Module . . . . . . . . . . . . . . . 35 103 6.2. Textual Conventions . . . . . . . . . . . . . . . . . . . 35 104 6.3. Statistical Counters . . . . . . . . . . . . . . . . . . . 35 105 6.4. Configuration Tables . . . . . . . . . . . . . . . . . . . 35 106 6.5. Relationship to Other MIB Modules . . . . . . . . . . . . 35 107 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 36 108 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 36 109 8. Operational Considerations . . . . . . . . . . . . . . . . . . 49 110 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 49 111 8.2. Notification Receiver Credential Selection . . . . . . . . 50 112 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 50 113 9. Security Considerations . . . . . . . . . . . . . . . . . . . 50 114 9.1. Certificates, Authentication, and Authorization . . . . . 51 115 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 52 116 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 52 117 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 118 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 53 119 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 120 12.1. Normative References . . . . . . . . . . . . . . . . . . . 53 121 12.2. Informative References . . . . . . . . . . . . . . . . . . 55 122 Appendix A. Target and Notificaton Configuration Example . . . . 56 123 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 58 124 Intellectual Property and Copyright Statements . . . . . . . . . . 59 126 1. Introduction 128 It is important to understand the SNMPv3 architecture [RFC3411], as 129 enhanced by the Transport Subsystem [I-D.ietf-isms-tmsm]. It is also 130 important to understand the terminology of the SNMPv3 architecture in 131 order to understand where the Transport Model described in this 132 document fits into the architecture and how it interacts with the 133 other architecture subsystems. For a detailed overview of the 134 documents that describe the current Internet-Standard Management 135 Framework, please refer to Section 7 of [RFC3410]. 137 This document describes a Transport Model that makes use of the 138 Datagram Transport Layer Security (DTLS) Protocol [RFC4347], the 139 datagram variant of the existing and commonly deployed Transport 140 Layer Security (TLS) protocol [RFC4346], within a transport subsystem 141 [I-D.ietf-isms-tmsm]. The Transport Model in this document is 142 referred to as the Datagram Transport Layer Security Transport Model 143 (DTLSTM). DTLS takes advantage of the X.509 public keying 144 infrastructure [X509]. This transport model is designed to meet the 145 security and operational needs of network administrators, operate in 146 environments where a connectionless (UDP) transport is preferred, and 147 integrate well into existing public keying infrastructures. 149 Managed objects are accessed via a virtual information store, termed 150 the Management Information Base or MIB. MIB objects are generally 151 accessed through the Simple Network Management Protocol (SNMP). 152 Objects in the MIB are defined using the mechanisms defined in the 153 Structure of Management Information (SMI). This document specifies a 154 MIB module that is compliant to the SMIv2, which is described in STD 155 58, RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579] and STD 58, RFC 156 2580 [RFC2580]. 158 This document also defines a portion of the Management Information 159 Base (MIB) for use with network management protocols in IP based 160 networks. In particular it defines objects for monitoring and 161 managing the DTLS Transport Model for SNMP. 163 The diagram shown below gives a conceptual overview of two SNMP 164 entities communicating using the DTLS Transport Model. One entity 165 contains a Command Responder and Notification Originator application, 166 and the other a Command Generator and Notification Responder 167 application. It should be understood that this particular mix of 168 application types is an example only and other combinations are 169 equally as legitimate. 171 +----------------------------------------------------------------+ 172 | Network | 173 +----------------------------------------------------------------+ 174 ^ ^ ^ ^ 175 |Notifications |Commands |Commands |Notifications 176 +---|---------------------|--------+ +--|---------------|-------------+ 177 | V V | | V V | 178 | +------------+ +------------+ | | +-----------+ +----------+ | 179 | | DTLS | | DTLS | | | | DTLS | | DTLS | | 180 | | Service | | Service | | | | Service | | Service | | 181 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 182 | +------------+ +------------+ | | +-----------+ +----------+ | 183 | ^ ^ | | ^ ^ | 184 | +--+----------+ | | +-+--------------+ | 185 | +-----|---------+----+ | | +---|--------+----+ | 186 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 187 | | +------+ +----+ | | | | | +------+ +----+ | | | 188 | | | DTLS | <---------->| Cache | | | | | DTLS | <---->| Cache | | 189 | | | TM | | | | | | | | TM | | | | | 190 | | +------+ | +-------+ | | | +------+ | +--------+ | 191 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 192 | +--------------------+ | | | +-----------------+ | | 193 | ^ +----+ | | ^ | | 194 | | | | | | | | 195 | v | | | V | | 196 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 197 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 198 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 199 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 200 | | | | | | | | | | | | | | | | | | 201 | | | | | |+---+| | | | | | | | |+---+| | | 202 | | | | +-----+ | || || | | | | | |+----+| || || | | 203 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 204 | | | | +-----+ | || || | | | | |+----+| || || | 205 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 206 | ^ | | | | | | ^ | | | | | 207 | | +----------+ +-----+ | | | +------+ +-----+ | 208 | +-+----------+ | | +-+------------+ | 209 | ^ ^ | | ^ ^ | 210 | | | | | | | | 211 | v v | | V V | 212 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 213 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 214 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RESPONDER | | 215 | | application | | applications | | | |application| | application | | 216 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 217 | SNMP entity | | SNMP entity | 218 +----------------------------------+ +--------------------------------+ 220 1.1. Requirements Terminology 222 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 223 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 224 document are to be interpreted as described in [RFC2119]. 226 1.2. Conventions 228 For consistency with SNMP-related specifications, this document 229 favors terminology as defined in STD62 rather than favoring 230 terminology that is consistent with non-SNMP specifications that use 231 different variations of the same terminology. This is consistent 232 with the IESG decision to not require the SNMPv3 terminology be 233 modified to match the usage of other non-SNMP specifications when 234 SNMPv3 was advanced to Full Standard. 236 In particular, where distinction is required the application names of 237 "Command Generator", "Command Responder", "Notification Originator", 238 "Notification Receiver", and "Proxy Forwarder" are used. See the 239 "SNMP Applications" in [RFC3413] for further information. 241 Authentication in this document typically refers to source 242 authentication or peer identity authentication performed in the 243 transport subsystem. 245 Throughout this document, the terms "client" and "server" are used to 246 refer to the two ends of the DTLS session. The client actively opens 247 the DTLS session, and the server passively listens for the incoming 248 DTLS session. Any SNMP entity may act as client or as server. 250 While security protocols frequently refer to a "user", the term used 251 in RFC3411 [RFC3411] and in this document is "principal". A 252 principal is the "who" on whose behalf services are provided or 253 processing takes place. A principal can be, among other things, an 254 individual acting in a particular role; a set of individuals, with 255 each acting in a particular role; an application or a set of 256 applications, or a combination of these within an administrative 257 domain. 259 Throughout this document, the term "session" is used to refer to a 260 secure association between two DTLS Transport Models that permits the 261 transmission of one or more SNMP messages within the lifetime of the 262 session. 264 2. The Datagram Transport Layer Security Protocol 266 The DTLS protocol is a datagram-compatible variant of the commonly 267 used Transport Layer Security (TLS) protocol. DTLS provides 268 authentication, data message integrity, and privacy at the transport 269 layer. (See [RFC4347]) 271 The primary goals of the DTLS Transport Model are to provide privacy, 272 source authentication and data integrity between two communicating 273 SNMP entities. The DTLS protocol is composed of two layers: the DTLS 274 Record Protocol and the DTLS Handshake Protocol. The following 275 sections provide an overview of these two layers. Please refer to 276 [RFC4347] for a complete description of the protocol. 278 2.1. The DTLS Record Protocol 280 At the lowest layer, layered on top of the transport protocol (UDP) 281 is the DTLS Record Protocol. 283 The DTLS Record Protocol provides security that has three basic 284 properties: 286 o The session can be confidential. Symmetric cryptography is used 287 for data encryption (e.g., AES [AES], DES [DES] etc.). The keys 288 for this symmetric encryption are generated uniquely for each 289 session and are based on a secret negotiated by another protocol 290 (such as the DTLS Handshake Protocol). The Record Protocol can 291 also be used without encryption. 293 o Messages can have data integrity. Message transport includes a 294 message integrity check using a keyed MAC. Secure hash functions 295 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 296 Protocol can operate without a MAC, but is generally only used in 297 this mode while another protocol is using the Record Protocol as a 298 transport for negotiating security parameters. 300 o Messages are protected against replay. DTLS uses explicit 301 sequence numbers, integrity checks, and a sliding window to 302 protect against replay of messages within a session. 304 DTLS also provides protection against replay of entire sessions. In 305 a properly-implemented keying material exchange, both sides will 306 generate new random numbers for each exchange. This results in 307 different encryption and integrity keys for every session. 309 2.2. The DTLS Handshake Protocol 311 The DTLS Record Protocol is used for encapsulation of various higher- 312 level protocols. One such encapsulated protocol, the DTLS Handshake 313 Protocol, allows server and client to authenticate each other and to 314 negotiate an encryption algorithm and cryptographic keys before the 315 application protocol transmits or receives its first octet of data. 316 Only the DTLS client can initiate the handshake protocol. The DTLS 317 Handshake Protocol provides security that has three basic properties: 319 o The peer's identity can be authenticated using asymmetric, or 320 public key, cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 321 authentication can be made optional, but is generally required by 322 at least one of the peers. 324 DTLS supports three authentication modes: authentication of both the 325 server and the client, server authentication with an unauthenticated 326 client, and total anonymity. For authentication of both entities, 327 each entity provides a valid certificate chain leading to an 328 acceptable certificate authority. Each entity is responsible for 329 verifying that the other's certificate is valid and has not expired 330 or been revoked. The DTLS Transport Model SHOULD always use 331 authentication of both the server and the client. At a minimum the 332 DTLS Transport MUST support authentication of the Command Generator 333 principals to guarantee the authenticity of the securityName (a 334 parameter used to pass the authenticated identity name from the 335 transport model to security model for even later use by the access 336 control subsystem. See Section 4.5.3.4). The DTLS Transport SHOULD 337 support the message encryption to protect sensitive data from 338 eavesdropping attacks. See [I-D.hodges-server-ident-check] for 339 further details on standardized processing when checking Server 340 certificate identities. 342 o The negotiation of a shared secret is secure: the negotiated 343 secret is unavailable to eavesdroppers, and for any authenticated 344 handshake the secret cannot be obtained, even by an attacker who 345 can place himself in the middle of the session. 347 o The negotiation is not vulnerable to malicious modification: it is 348 infeasible for an attacker to modify negotiation communication 349 without being detected by the parties to the communication. 351 o DTLS uses a stateless cookie exchange to protect against anonymous 352 denial of service attacks and has retransmission timers, sequence 353 numbers, and counters to handle message loss, reordering, and 354 fragmentation. 356 3. How the DTLSTM fits into the Transport Subsystem 358 A transport model is a component of the Transport Subsystem. The 359 DTLS Transport Model thus fits between the underlying DTLS transport 360 layer and the message Dispatcher [RFC3411] component of the SNMP 361 engine and the Transport Subsystem [I-D.ietf-isms-tmsm]. 363 The DTLS Transport Model will establish a session between itself and 364 the DTLS Transport Model of another SNMP engine. The sending 365 transport model passes unprotected messages from the dispatcher to 366 DTLS to be protected, and the receiving transport model accepts 367 decrypted and authenticated/integrity-checked incoming messages from 368 DTLS and passes them to the dispatcher. 370 After a DTLS Transport model session is established, SNMP messages 371 can conceptually be sent through the session from one SNMP message 372 dispatcher to another SNMP message dispatcher. If multiple SNMP 373 messages are needed to be passed between two SNMP applications they 374 SHOULD be passed through the same session. A DTLSTM implementation 375 engine MAY choose to close a DTLS session to conserve resources. 377 The DTLS Transport Model of an SNMP engine will perform the 378 translation between DTLS-specific security parameters and SNMP- 379 specific, model-independent parameters. 381 The diagram below depicts where the DTLS Transport Model fits into 382 the architecture described in RFC3411 and the Transport Subsystem: 384 +------------------------------+ 385 | Network | 386 +------------------------------+ 387 ^ ^ ^ 388 | | | 389 v v v 390 +-------------------------------------------------------------------+ 391 | +--------------------------------------------------+ | 392 | | Transport Subsystem | +--------+ | 393 | | +-----+ +-----+ +-----+ +-----+ +-------+ | | | | 394 | | | UDP | | TCP | | SSH | |DTLS | . . . | other |<--->| Cache | | 395 | | | | | | | TM | TM | | | | | | | 396 | | +-----+ +-----+ +-----+ +-----+ +-------+ | +--------+ | 397 | +--------------------------------------------------+ ^ | 398 | ^ | | 399 | | | | 400 | Dispatcher v | | 401 | +--------------+ +---------------------+ +----------------+ | | 402 | | Transport | | Message Processing | | Security | | | 403 | | Dispatch | | Subsystem | | Subsystem | | | 404 | | | | +------------+ | | +------------+ | | | 405 | | | | +->| v1MP |<--->| | USM | | | | 406 | | | | | +------------+ | | +------------+ | | | 407 | | | | | +------------+ | | +------------+ | | | 408 | | | | +->| v2cMP |<--->| | Transport | | | | 409 | | Message | | | +------------+ | | | Security |<--+ | 410 | | Dispatch <---->| +------------+ | | | Model | | | 411 | | | | +->| v3MP |<--->| +------------+ | | 412 | | | | | +------------+ | | +------------+ | | 413 | | PDU Dispatch | | | +------------+ | | | Other | | | 414 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 415 | ^ | +------------+ | | +------------+ | | 416 | | +---------------------+ +----------------+ | 417 | v | 418 | +-------+-------------------------+---------------+ | 419 | ^ ^ ^ | 420 | | | | | 421 | v v v | 422 | +-------------+ +---------+ +--------------+ +-------------+ | 423 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 424 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 425 | | application | | | | applications | | application | | 426 | +-------------+ +---------+ +--------------+ +-------------+ | 427 | ^ ^ | 428 | | | | 429 | v v | 430 | +----------------------------------------------+ | 431 | | MIB instrumentation | SNMP entity | 432 +-------------------------------------------------------------------+ 434 3.1. Security Capabilities of this Model 436 3.1.1. Threats 438 The DTLS Transport Model provides protection against the threats 439 identified by the RFC 3411 architecture [RFC3411]: 441 1. Modification of Information - The modification threat is the 442 danger that some unauthorized entity may alter in-transit SNMP 443 messages generated on behalf of an authorized principal in such a 444 way as to effect unauthorized management operations, including 445 falsifying the value of an object. 447 DTLS provides verification that the content of each received 448 message has not been modified during its transmission through the 449 network, data has not been altered or destroyed in an 450 unauthorized manner, and data sequences have not been altered to 451 an extent greater than can occur non-maliciously. 453 2. Masquerade - The masquerade threat is the danger that management 454 operations unauthorized for a given principal may be attempted by 455 assuming the identity of a principal with appropriate 456 authorizations. 458 The DTLSTM provides for authentication of the Principal Command 459 Generator and Notification Generator and for authentication of 460 the Command Responder, Notification Responder and Proxy Forwarder 461 through the use of X.509 certificates. 463 The masquerade threat can be mitigated against by using an 464 appropriate Access Control Model (ACM) such as the View-based 465 Access Control Module (VACM) [RFC3415]. In addition, it is 466 important to authenticate and verify both the authenticated 467 identity of the DTLS client and the DTLS server to protect 468 against this threat. (See Section 9 for more detail.) 470 3. Message stream modification - The re-ordering, delay or replay of 471 messages can and does occur through the natural operation of many 472 connectionless transport services. The message stream 473 modification threat is the danger that messages may be 474 maliciously re-ordered, delayed or replayed to an extent which is 475 greater than can occur through the natural operation of 476 connectionless transport services, in order to effect 477 unauthorized management operations. 479 DTLS provides replay protection with a MAC that includes a 480 sequence number. DTLS uses a sliding window protocol with the 481 sequence number for replay protection, see [RFC4347]. The 482 technique used is the same as in IPsec AH/ESP [RFC4302] 483 [RFC4303], by maintaining a bitmap window of received records. 484 Records that are too old to fit in the window and records that 485 have previously been received are silently discarded. The replay 486 detection feature is optional, since packet duplication can also 487 occur naturally due to routing errors and does not necessarily 488 indicate an active attack. Applications may conceivably detect 489 duplicate packets and accordingly modify their data transmission 490 strategy. 492 4. Disclosure - The disclosure threat is the danger of eavesdropping 493 on the exchanges between SNMP engines. Protecting against this 494 threat may be required as a matter of local policy. 496 Symmetric cryptography (e.g., AES [AES], DES [DES] etc.) can be 497 used by DTLS for data privacy. The keys for this symmetric 498 encryption are generated uniquely for each session and are based 499 on a secret negotiated by another protocol (such as the DTLS 500 Handshake Protocol). 502 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 503 that denial of service (DoS) attacks need not be addressed by an 504 SNMP security protocol. However, datagram security protocols are 505 susceptible to a variety of denial of service attacks. Two 506 attacks are of particular concern: 508 o An attacker can consume excessive resources on the server by 509 transmitting a series of handshake initiation requests, 510 causing the server to allocate state and potentially to 511 perform expensive cryptographic operations. 513 o An attacker can use the server as an amplifier by sending 514 session initiation messages with a forged source of the 515 victim. The server then sends its next message (in DTLS, a 516 Certificate message, which can be quite large) to the victim 517 machine, thus flooding it. 519 In order to counter both of these attacks, DTLS borrows the 520 stateless cookie technique used by Photuris [RFC2522] and IKEv2 521 [RFC4306]. When the client sends its ClientHello message to the 522 server, the server MAY respond with a HelloVerifyRequest message. 523 This message contains a stateless cookie generated using the 524 technique of [RFC2522]. The client MUST retransmit the 525 ClientHello with the cookie added. The server then verifies the 526 cookie and proceeds with the handshake only if it is valid. This 527 mechanism forces the attacker/client to be able to receive the 528 cookie, which makes DoS attacks with spoofed IP addresses 529 difficult. This mechanism does not provide any defense against 530 denial of service attacks mounted from valid IP addresses. 532 Implementations are not required to perform the stateless cookie 533 exchange for every DTLS handshakes but in environments where 534 amplification could be an issue it is RECOMMENDED that the cookie 535 exchange is utilized. 537 3.1.2. Message Protection 539 The RFC 3411 architecture recognizes three levels of security: 541 o without authentication and without privacy (noAuthNoPriv) 543 o with authentication but without privacy (authNoPriv) 545 o with authentication and with privacy (authPriv) 547 The DTLS Transport Model determines from DTLS the identity of the 548 authenticated principal, and the type and address associated with an 549 incoming message, and the DTLS Transport Model provides this 550 information to DTLS for an outgoing message. 552 When an application requests a session for a message, through the 553 cache, the application requests a security level for that session. 554 The DTLS Transport Model MUST ensure that the DTLS session provides 555 security at least as high as the requested level of security. How 556 the security level is translated into the algorithms used to provide 557 data integrity and privacy is implementation-dependent. However, the 558 NULL integrity and encryption algorithms MUST NOT be used to fulfill 559 security level requests for authentication or privacy. 560 Implementations MAY choose to force DTLS to only allow cipher_suites 561 that provide both authentication and privacy to guarantee this 562 assertion. 564 If a suitable interface between the DTLS Transport Model and the DTLS 565 Handshake Protocol is implemented to allow the selection of security 566 level dependent algorithms, for example a security level to 567 cipher_suites mapping table, then different security levels may be 568 utilized by the application. However, different port numbers will 569 need to be used by at least one side of the connection to 570 differentiate between the DTLS sessions. This is the only way to 571 ensured proper selection of a session ID for an incoming DTLS 572 message. 574 The authentication, integrity and privacy algorithms used by the DTLS 575 Protocol [RFC4347] may vary over time as the science of cryptography 576 continues to evolve and the development of DTLS continues over time. 577 Implementers are encouraged to plan for changes in operator trust of 578 particular algorithms and implementations should offer configuration 579 settings for mapping algorithms to SNMPv3 security levels. 581 3.1.3. DTLS Sessions 583 DTLS sessions are opened by the DTLS Transport Model during the 584 elements of procedure for an outgoing SNMP message. Since the sender 585 of a message initiates the creation of a DTLS session if needed, the 586 DTLS session will already exist for an incoming message. 588 Implementations MAY choose to instantiate DTLS sessions in 589 anticipation of outgoing messages. This approach might be useful to 590 ensure that a DTLS session to a given target can be established 591 before it becomes important to send a message over the DTLS session. 592 Of course, there is no guarantee that a pre-established session will 593 still be valid when needed. 595 DTLS sessions are uniquely identified within the DTLS Transport Model 596 by the combination of transportDomain, transportAddress, 597 securityName, and requestedSecurityLevel associated with each 598 session. Each unique combination of these parameters MUST have a 599 locally-chosen unique dtlsSessionID associated for active sessions. 600 For further information see Section 4.4 and Section 5. 602 3.2. Security Parameter Passing 604 For the DTLS server-side, DTLS-specific security parameters (i.e., 605 cipher_suites, X.509 certificate fields, IP address and port) are 606 translated by the DTLS Transport Model into security parameters for 607 the DTLS Transport Model and security model (i.e., securityLevel, 608 securityName, transportDomain, transportAddress). The transport- 609 related and DTLS-security-related information, including the 610 authenticated identity, are stored in a cache referenced by 611 tmStateReference. 613 For the DTLS client-side, the DTLS Transport Model takes input 614 provided by the dispatcher in the sendMessage() Abstract Service 615 Interface (ASI) and input from the tmStateReference cache. The DTLS 616 Transport Model converts that information into suitable security 617 parameters for DTLS and establishes sessions as needed. 619 The elements of procedure in Section 5 discuss these concepts in much 620 greater detail. 622 3.3. Notifications and Proxy 624 DTLS sessions may be initiated by DTLS clients on behalf of command 625 generators or notification originators. Command generators are 626 frequently operated by a human, but notification originators are 627 usually unmanned automated processes. The targets to whom 628 notifications should be sent is typically determined and configured 629 by a network administrator. 631 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 632 management targets, including transportDomain, transportAddress, 633 securityName, securityModel, and securityLevel parameters, for 634 Notification Generator, Proxy Forwarder, and SNMP-controllable 635 Command Generator applications. Transport domain and transport 636 address are configured in the snmpTargetAddrTable, and the 637 securityModel, securityName, and securityLevel parameters are 638 configured in the snmpTargetParamsTable. This document defines a MIB 639 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 640 specify a DTLS client-side certificate to use for the connection. 642 When configuring a DTLS target, the snmpTargetAddrTDomain and 643 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 644 set to the snmpDTLSDomain object and an appropriate snmpDTLSAddress 645 value respectively. The snmpTargetParamsMPModel column of the 646 snmpTargetParamsTable should be set to a value of 3 to indicate the 647 SNMPv3 message processing model. The snmpTargetParamsSecurityName 648 should be set to an appropriate securityName value and the 649 dtlstmParamsHashType and dtlstmParamsHashValue parameters of the 650 dtlstmParamsTable should be set to values that refer to a locally 651 held certificate to be used. Other parameters, for example 652 cryptographic configuration such as cipher suites to use, must come 653 from configuration mechanisms not defined in this document. The 654 other needed configuration may be configured using SNMP or other 655 implementation-dependent mechanisms (for example, via a CLI). This 656 securityName defined in the snmpTargetParamsSecurityName column will 657 be used by the access control model to authorize any notifications 658 that need to be sent. 660 4. Elements of the Model 662 This section contains definitions required to realize the DTLS 663 Transport Model defined by this document. 665 4.1. Certificates 667 DTLS makes use of X.509 certificates for authentication of both sides 668 of the transport. This section discusses the use of certificates in 669 DTLS and the its effects on SNMP over DTLS. 671 4.1.1. The Certificate Infrastructure 673 Users of a public key SHALL be confident that the associated private 674 key is owned by the correct remote subject (person or system) with 675 which an encryption or digital signature mechanism will be used. 676 This confidence is obtained through the use of public key 677 certificates, which are data structures that bind public key values 678 to subjects. The binding is asserted by having a trusted CA 679 digitally sign each certificate. The CA may base this assertion upon 680 technical means (i.e., proof of possession through a challenge- 681 response protocol), presentation of the private key, or on an 682 assertion by the subject. A certificate has a limited valid lifetime 683 which is indicated in its signed contents. Because a certificate's 684 signature and timeliness can be independently checked by a 685 certificate-using client, certificates can be distributed via 686 untrusted communications and server systems, and can be cached in 687 unsecured storage in certificate-using systems. 689 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8, which was 690 first published in 1988 as part of the X.500 Directory 691 recommendations, defines a standard certificate format [X509] which 692 is a certificate which binds a subject (principal) to a public key 693 value. This was later further documented in [RFC5280]. 695 A X.509 certificate is a sequence of three required fields: 697 tbsCertificate: The field contains the names of the subject and 698 issuer, a public key associated with the subject, a validity 699 period, and other associated information. This field may also 700 contain extensions. 702 signatureAlgorithm: The signatureAlgorithm field contains the 703 identifier for the cryptographic algorithm used by the certificate 704 authority (CA) to sign this certificate. 706 signatureValue: The signatureValue field contains a digital 707 signature computed upon the ASN.1 DER encoded tbsCertificate 708 field. The ASN.1 DER encoded tbsCertificate is used as the input 709 to the signature function. This signature value is then ASN.1 DER 710 encoded as a BIT STRING and included in the Certificate's 711 signature field. By generating this signature, a CA certifies the 712 validity of the information in the tbsCertificate field. In 713 particular, the CA certifies the binding between the public key 714 material and the subject of the certificate. 716 The basic X.509 authentication procedure is as follows: A system is 717 initialized with a number of root certificates that contain the 718 public keys of a number of trusted CAs. When a system receives a 719 X.509 certificate, signed by one of those CAs, the certificate has to 720 be verified. It first checks the signatureValue field by using the 721 public key of the corresponding trusted CA. Then it compares the 722 decrypted information with a digest of the tbsCertificate field. If 723 they match, then the subject in the tbsCertificate field is 724 authenticated. 726 4.1.2. Provisioning for the Certificate 728 Authentication using DTLS will require that SNMP entities are 729 provisioned with certificates, which are signed by trusted 730 certificate authorities. Furthermore, SNMP entities will most 731 commonly need to be provisioned with root certificates which 732 represent the list of trusted certificate authorities that an SNMP 733 entity can use for certificate verification. SNMP entities MAY also 734 be provisioned with a X.509 certificate revocation mechanism which 735 can be used to verify that a certificate has not been revoked. 737 The authenticated tmSecurityName of the principal is looked up using 738 the dtlstmCertificateToSNTable. This table either: 740 o Maps a certificate's fingerprint hash type and value to a directly 741 specified tmSecurityName. 743 o Identifies a certificate issuer's fingerprint hash type and value 744 and allows child certificate's subjectAltName or CommonName to 745 directly used as the tmSecurityNome. 747 The certificate trust anchors, being either CA certificates or public 748 keys for use by self-signed certificates, must be installed through 749 an out of band trusted mechanism into the server and its authenticity 750 MUST be verified before access is granted. Implementations SHOULD 751 choose to discard any connections for which no potential 752 dtlstmCertificateToSNTable mapping exists before performing 753 certificate verification to avoid expending computational resources 754 associated with certificate verification. 756 The typical enterprise configuration will map the "subjectAltName" 757 component of the tbsCertificate to the DTLSSM specific 758 tmSecurityName. Thus, the authenticated identity can be obtained by 759 the DTLS Transport Model by extracting the subjectAltName from the 760 peer's certificate and the receiving application will have an 761 appropriate tmSecurityName for use by components like an access 762 control model. This setup requires very little configuration: a 763 single row in the dtlstmCertificateToSNTable referencing a 764 certificate authority. 766 An example mapping setup can be found in Appendix A 768 This tmSecurityName may be later translated from a DTLSSM specific 769 tmSecurityName to a SNMP engine securityName by the security model. 770 A security model, like the TSM security model, may perform an 771 identity mapping or a more complex mapping to derive the securityName 772 from the tmSecurityName offered by the DTLS Transport Model. 774 4.2. Messages 776 As stated in RFC4347, each DTLS message must fit within a single 777 datagram. The DTLSTM MUST prohibit SNMP messages from being set that 778 exceed the MTU size. The DTLSTM implementation MUST return an error 779 when the MTU size would be exceeded and the message won't be sent. 781 For Ethernet the MTU size is 1500 and thus the maximum allowable SNMP 782 message that can be sent over DTLSTM after UDP/IP/DTLS overhead is 783 taken into account will be 1455 for IPv6 (MTU:1500 - IPv6:40 - UDP:8 784 - DTLS:13) and 1475 for IPv4 (MTU:1500 - IPv4:20 - UDP:8 - DTLS:13). 785 From this integrity and encryption overhead also needs to be 786 subtracted, which are integrity and encryption algorithm specific. 788 4.3. SNMP Services 790 This section describes the services provided by the DTLS Transport 791 Model with their inputs and outputs. The services are between the 792 Transport Model and the Dispatcher. 794 The services are described as primitives of an abstract service 795 interface (ASI) and the inputs and outputs are described as abstract 796 data elements as they are passed in these abstract service 797 primitives. 799 4.3.1. SNMP Services for an Outgoing Message 801 The Dispatcher passes the information to the DTLS Transport Model 802 using the ASI defined in the transport subsystem: 804 statusInformation = 805 sendMessage( 806 IN destTransportDomain -- transport domain to be used 807 IN destTransportAddress -- transport address to be used 808 IN outgoingMessage -- the message to send 809 IN outgoingMessageLength -- its length 810 IN tmStateReference -- reference to transport state 811 ) 813 The abstract data elements passed as parameters in the abstract 814 service primitives are as follows: 816 statusInformation: An indication of whether the passing of the 817 message was successful. If not it is an indication of the 818 problem. 820 destTransportDomain: The transport domain for the associated 821 destTransportAddress. The Transport Model uses this parameter to 822 determine the transport type of the associated 823 destTransportAddress. This parameter may also be used by the 824 transport subsystem to route the message to the appropriate 825 Transport Model. 827 destTransportAddress: The transport address of the destination DTLS 828 Transport Model in a format specified by the SnmpDTLSAddress 829 TEXTUAL-CONVENTION. 831 outgoingMessage: The outgoing message to send to DTLS for 832 encapsulation. 834 outgoingMessageLength: The length of the outgoing message. 836 tmStateReference: A handle/reference to tmSecurityData to be used 837 when securing outgoing messages. 839 4.3.2. SNMP Services for an Incoming Message 841 The DTLS Transport Model processes the received message from the 842 network using the DTLS service and then passes it to the Dispatcher 843 using the following ASI: 845 receiveMessage( 846 IN transportDomain -- origin transport domain 847 IN transportAddress -- origin transport address 848 IN incomingMessage -- the message received 849 IN incomingMessageLength -- its length 850 IN tmStateReference -- reference to transport state 851 ) 853 The abstract data elements passed as parameters in the abstract 854 service primitives are as follows: 856 statusInformation: An indication of whether the passing of the 857 message was successful. If not it is an indication of the 858 problem. 860 transportDomain: The transport domain for the associated 861 transportAddress. 863 transportAddress: The transport address of the source of the 864 received message in a format specified by the SnmpDTLSAddress 865 TEXTUAL-CONVENTION. 867 incomingMessage: The whole SNMP message stripped of all DTLS 868 protection data. 870 incomingMessageLength: The length of the SNMP message after being 871 processed by DTLS. 873 tmStateReference: A handle/reference to tmSecurityData to be used by 874 the security model. 876 4.4. DTLS Services 878 This section describes the services provided by the DTLS Transport 879 Model with their inputs and outputs. These services are between the 880 DTLS Transport Model and the DTLS transport layer. The following 881 sections describe services for establishing and closing a session and 882 for passing messages between the DTLS transport layer and the DTLS 883 Transport Model. 885 4.4.1. Services for Establishing a Session 887 The DTLS Transport Model provides the following ASI to describe the 888 data passed between the Transport Model and the DTLS transport layer 889 for session establishment. 891 statusInformation = -- errorIndication or success 892 openSession( 893 IN destTransportDomain -- transport domain to be used 894 IN destTransportAddress -- transport address to be used 895 IN securityName -- on behalf of this principal 896 IN securityLevel -- Level of Security requested 897 OUT dtlsSessionID -- Session identifier for DTLS 898 ) 900 The abstract data elements passed as parameters in the abstract 901 service primitives are as follows: 903 statusInformation: An indication of whether the process was 904 successful or not. If not, then the status information will 905 include the error indication provided by DTLS. 907 destTransportDomain: The transport domain for the associated 908 destTransportAddress. The DTLS Transport Model uses this 909 parameter to determine the transport type of the associated 910 destTransportAddress. 912 destTransportAddress: The transport address of the destination DTLS 913 Transport Model in a format specified by the SnmpDTLSAddress 914 TEXTUAL-CONVENTION. 916 securityName: The security name representing the principal on whose 917 behalf the message will be sent. 919 securityLevel: The level of security requested by the application. 921 dtlsSessionID: An implementation-dependent session identifier to 922 reference the specific DTLS session. 924 DTLS and UDP do not provide a session de-multiplexing mechanism and 925 it is possible that implementations will only be able to identify a 926 unique session based on a unique combination of source address, 927 destination address, source UDP port number and destination UDP port 928 number. Because of this, when establishing a new sessions 929 implementations MUST use a different UDP source port number for each 930 connection to a remote destination IP-address/port-number combination 931 to ensure the remote entity can properly disambiguate between 932 multiple sessions from a host to the same port on a server. 934 The procedural details for establishing a session are further 935 described in Section 5.3. 937 Upon completion of the process the DTLS Transport Model returns 938 status information and, if the process was successful the 939 dtlsSessionID and other implementation-dependent data from DTLS are 940 also returned. The dtlsSessionID is stored in an implementation- 941 dependent manner and tied to the tmSecurityData for future use of 942 this session. 944 4.4.2. DTLS Services for an Incoming Message 946 When the DTLS Transport Model invokes the DTLS record layer to verify 947 proper security for the incoming message, it must use the following 948 ASI: 950 statusInformation = -- errorIndication or success 951 dtlsRead( 952 IN dtlsSessionID -- Session identifier for DTLS 953 IN wholeDtlsMsg -- as received on the wire 954 IN wholeDtlsMsgLength -- length as received on the wire 955 OUT incomingMessage -- the whole SNMP message from DTLS 956 OUT incomingMessageLength -- the length of the SNMP message 957 ) 959 The abstract data elements passed as parameters in the abstract 960 service primitives are as follows: 962 statusInformation: An indication of whether the process was 963 successful or not. If not, then the status information will 964 include the error indication provided by DTLS. 966 dtlsSessionID: An implementation-dependent session identifier to 967 reference the specific DTLS session. How the DTLS session ID is 968 obtained for each message is implementation-dependent. As an 969 implementation hint, the DTLS Transport Model can examine incoming 970 messages to determine the source IP address and port number and 971 use these values to look up the local DTLS session ID in the list 972 of active sessions. 974 wholeDtlsMsg: The whole message as received on the wire. 976 wholeDtlsMsgLength: The length of the message as it was received on 977 the wire. 979 incomingMessage: The whole SNMP message stripped of all DTLS privacy 980 and integrity data. 982 incomingMessageLength: The length of the SNMP message stripped of 983 all DTLS privacy and integrity data. 985 4.4.3. DTLS Services for an Outgoing Message 987 When the DTLS Transport Model invokes the DTLS record layer to 988 encapsulate and transmit a SNMP message, it must use the following 989 ASI. 991 statusInformation = -- errorIndication or success 992 dtlsWrite( 993 IN dtlsSessionID -- Session identifier for DTLS 994 IN outgoingMessage -- the message to send 995 IN outgoingMessageLength -- its length 996 ) 998 The abstract data elements passed as parameters in the abstract 999 service primitives are as follows: 1001 statusInformation: An indication of whether the process was 1002 successful or not. If not, then the status information will 1003 include the error indication provided by DTLS. 1005 dtlsSessionID: An implementation-dependent session identifier to 1006 reference the specific DTLS session that the message should be 1007 sent using. 1009 outgoingMessage: The outgoing message to send to DTLS for 1010 encapsulation. 1012 outgoingMessageLength: The length of the outgoing message. 1014 4.5. Cached Information and References 1016 When performing SNMP processing, there are two levels of state 1017 information that may need to be retained: the immediate state linking 1018 a request-response pair, and potentially longer-term state relating 1019 to transport and security. 1021 The RFC3411 architecture uses caches to maintain the short-term 1022 message state, and uses references in the ASIs to pass this 1023 information between subsystems. 1025 This document defines the requirements for a cache to handle the 1026 longer-term transport state information, using a tmStateReference 1027 parameter to pass this information between subsystems. 1029 To simplify the elements of procedure, the release of state 1030 information is not always explicitly specified. As a general rule, 1031 if state information is available when a message being processed gets 1032 discarded, the state related to that message SHOULD also be 1033 discarded. If state information is available when a relationship 1034 between engines is severed, such as the closing of a transport 1035 session, the state information for that relationship SHOULD also be 1036 discarded. 1038 Since the contents of a cache are meaningful only within an 1039 implementation, and not on-the-wire, the format of the cache and the 1040 LCD are implementation-specific. 1042 4.5.1. securityStateReference 1044 The securityStateReference parameter is defined in RFC3411. Its 1045 primary purpose is to provide a mapping between a request and the 1046 corresponding response. This cache is not accessible to Transport 1047 Models, and an entry is typically only retained for the lifetime of a 1048 request-response pair of messages. 1050 4.5.2. tmStateReference 1052 For each transport session, information about the transport security 1053 is stored in a cache. The tmStateReference parameter is used to pass 1054 model-specific and mechanism-specific parameters between the 1055 Transport subsystem and transport-aware Security Models. 1057 The tmStateReference cache will typically remain valid for the 1058 duration of the transport session, and hence may be used for several 1059 messages. 1061 Since this cache is only used within an implementation, and not on- 1062 the-wire, the precise contents and format are implementation- 1063 dependent. However, for interoperability between Transport Models 1064 and transport-aware Security Models, entries in this cache must 1065 include at least the following fields: 1067 transportDomain 1069 transportAddress 1070 tmSecurityName 1072 tmRequestedSecurityLevel 1074 tmTransportSecurityLevel 1076 tmSameSecurity 1078 tmSessionID 1080 4.5.2.1. Transport information 1082 Information about the source of an incoming SNMP message is passed up 1083 from the Transport subsystem as far as the Message Processing 1084 subsystem. However these parameters are not included in the 1085 processIncomingMsg ASI defined in RFC3411, and hence this information 1086 is not directly available to the Security Model. 1088 A transport-aware Security Model might wish to take account of the 1089 transport protocol and originating address when authenticating the 1090 request, and setting up the authorization parameters. It is 1091 therefore necessary for the Transport Model to include this 1092 information in the tmStateReference cache, so that it is accessible 1093 to the Security Model. 1095 o transportDomain: the transport protocol (and hence the Transport 1096 Model) used to receive the incoming message 1098 o transportAddress: the source of the incoming message. 1100 The ASIs used for processing an outgoing message all include explicit 1101 transportDomain and transportAddress parameters. The values within 1102 the securityStateReference cache might override these parameters for 1103 outgoing messages. 1105 4.5.2.2. securityName 1107 There are actually three distinct "identities" that can be identified 1108 during the processing of an SNMP request over a secure transport: 1110 o transport principal: the transport-authenticated identity, on 1111 whose behalf the secure transport connection was (or should be) 1112 established. This value is transport-, mechanism- and 1113 implementation- specific, and is only used within a given 1114 Transport Model. 1116 o tmSecurityName: a human-readable name (in snmpAdminString format) 1117 representing this transport identity. This value is transport- 1118 and implementation-specific, and is only used (directly) by the 1119 Transport and Security Models. 1121 o securityName: a human-readable name (in snmpAdminString format) 1122 representing the SNMP principal in a model-independent manner. 1124 The transport principal may or may not be the same as the 1125 tmSecurityName. Similarly, the tmSecurityName may or may not be the 1126 same as the securityName as seen by the Application and Access 1127 Control subsystems. In particular, a non-transport-aware Security 1128 Model will ignore tmSecurityName completely when determining the SNMP 1129 securityName. 1131 However it is important that the mapping between the transport 1132 principal and the SNMP securityName (for transport-aware Security 1133 Models) is consistent and predictable, to allow configuration of 1134 suitable access control and the establishment of transport 1135 connections. 1137 4.5.2.3. securityLevel 1139 There are two distinct issues relating to security level as applied 1140 to secure transports. For clarity, these are handled by separate 1141 fields in the tmStateReference cache: 1143 o tmTransportSecurityLevel: an indication from the Transport Model 1144 of the level of security offered by this session. The Security 1145 Model can use this to ensure that incoming messages were suitably 1146 protected before acting on them. 1148 o tmRequestedSecurityLevel: an indication from the Security Model of 1149 the level of security required to be provided by the transport 1150 protocol. The Transport Model can use this to ensure that 1151 outgoing messages will not be sent over an insufficiently secure 1152 session. 1154 4.5.2.4. Session Information 1156 For security reasons, if a secure transport session is closed between 1157 the time a request message is received and the corresponding response 1158 message is sent, then the response message SHOULD be discarded, even 1159 if a new session has been established. The SNMPv3 WG decided that 1160 this should be a SHOULD architecturally, and it is a security-model- 1161 specific decision whether to REQUIRE this. 1163 o tmSameSecurity: this flag is used by a transport-aware Security 1164 Model to indicate whether the Transport Model MUST enforce this 1165 restriction. 1167 o tmSessionID: in order to verify whether the session has changed, 1168 the Transport Model must be able to compare the session used to 1169 receive the original request with the one to be used to send the 1170 response. This typically requires some form of session 1171 identifier. This value is only ever used by the Transport Model, 1172 so the format and interpretation of this field are model-specific 1173 and implementation-dependent. 1175 When processing an outgoing message, if tmSameSecurity is true, then 1176 the tmSessionID MUST match the current transport session, otherwise 1177 the message MUST be discarded, and the dispatcher notified that 1178 sending the message failed. 1180 4.5.3. DTLS Transport Model Cached Information 1182 For the DTLS Transport Model, the session state is maintained using 1183 tmStateReference. Upon opening each DTLS session, the DTLS Transport 1184 Model stores model- and mechanism-specific information about the 1185 session in a cache, referenced by tmStateReference. An 1186 implementation might store the contents of the cache in a Local 1187 Configuration Datastore (LCD). 1189 At a minimum, the following parameters are stored in the cache: 1191 tmTransportDomain = Specified by the application tmSameSecurity = 1192 boolean value set by the security model or false by default 1194 tmTransportAddress = Specified by the application 1196 tmRequestedSecurityLevel = ["noAuthNoPriv" | "authNoPriv" | 1197 "authPriv" ] the security level requested by the application 1199 tmSecurityLevel = ["noAuthNoPriv" | "authNoPriv" | "authPriv" ] the 1200 security level of the established DTLS session 1202 tmSecurityName = the security name associated with a principal 1204 The tmStateReference cache is used to pass a reference to these 1205 values between the DTLS Transport Model and the security model. 1207 The DTLS Transport Model has the responsibility for releasing the 1208 complete tmStateReference and deleting the associated information 1209 when the session is destroyed. 1211 4.5.3.1. Transport Information 1213 The tmTransportDomain and tmTransportAddress identify the type and 1214 address of the remote DTLS transport endpoint. The domain for 1215 address types for DTLS sessions SHOULD be "snmpDTLSDomain" and the 1216 address SHOULD be one that conforms to the details specified in the 1217 "SnmpDTLSAddress" textual convention. 1219 4.5.3.2. tmRequestedSecurityLevel 1221 The tmRequestedSecurityLevel is the security level requested by the 1222 application. This parameter is set in the cache by the security 1223 model and used by DTLS Transport Model initiating a session to select 1224 the appropriate cipher_suites and other configuration needed settings 1225 for establishing the session. The DTLS Transport Model MUST ensure 1226 that the actual security provided by the session (tmSecurityLevel) is 1227 at least as high as the requested security level 1228 (tmRequestedSecurityLevel). 1230 4.5.3.3. tmSecurityLevel 1232 The tmSecurityLevel is the actual security level of the established 1233 session. See Section 3.1.2 for more detail about security levels. 1234 How the chosen cipher_suites and other DTLS session parameters are 1235 translated into a security level at the DTLS Transport Model is 1236 implementation dependent and/or policy specific. Implementations 1237 MUST NOT use NULL algorithms for fulfilling authentication or 1238 encryption needs indicated by the tmSecurityLevel. 1240 4.5.3.4. tmSecurityName 1242 The tmSecurityName is the name of the principal on whose behalf the 1243 message is being sent. This field is set via the mapping defined in 1244 the dtlstmCertificateToSNTable when mapping incoming client 1245 connection certificates to a tmSecurityName. For outgoing 1246 connections, the application will specify the value that should be 1247 placed in this field (possibly by extracting it from the SNMP-TARGET- 1248 MIB's snmpTargetParamsSecurityName value). 1250 4.5.4. Transport Model LCD 1252 Implementations may store DTLS-specific and model-specific 1253 information in a LCD. The DTLS session ID is one such parameter that 1254 could be stored in the LCD. When messages are to be routed for 1255 encapsulation or for integrity verification and decryption the 1256 message and the DTLS session ID must be passed to the DTLS transport 1257 layer for processing. Therefore, the DTLS Transport Model MUST 1258 maintain a one-to-one mapping between the DTLS session ID and the 1259 tmStateReference cache entry for that session. Implementations will 1260 need to store the DTLS session ID in the tmStateReference cache to 1261 simplify the procedure. 1263 5. Elements of Procedure 1265 Abstract service interfaces have been defined by RFC 3411 to describe 1266 the conceptual data flows between the various subsystems within an 1267 SNMP entity. The DTLSTM uses some of these conceptual data flows 1268 when communicating between subsystems. These RFC 3411-defined data 1269 flows are referred to here as public interfaces. 1271 To simplify the elements of procedure, the release of state 1272 information is not always explicitly specified. As a general rule, 1273 if state information is available when a message gets discarded, the 1274 message-state information should also be released. If state 1275 information is available when a session is closed, the session state 1276 information should also be released. Sensitive information, like 1277 cryptographic keys, should be overwritten with zero value or random 1278 value data prior to being released. 1280 An error indication may return an OID and value for an incremented 1281 counter if the information is available at the point where the error 1282 is detected. 1284 5.1. Procedures for an Incoming Message 1286 The following section describes the procedures followed by the DTLS 1287 Transport Model when it receives a DTLS protected packet. The steps 1288 are broken into two different sections. The first section describes 1289 the needed steps for de-multiplexing multiple DTLS sessions and the 1290 second section describes the steps which are specific to transport 1291 processing once the DTLS processing has been completed. 1293 5.1.1. DTLS Processing for Incoming Messages 1295 DTLS is significantly different in terms of session handling than 1296 SSH, TLS or other TCP-based session streams. The DTLS protocol, 1297 which is UDP-based, does not have a session identifier that allows 1298 implementations to determine through which session a packet is 1299 arriving like TCP-based streams have. Thus, a process for de- 1300 multiplexing sessions must be incorporated into the procedures for an 1301 incoming message. The steps in this section describe how this can be 1302 accomplished, although any implementation dependent method for doing 1303 so should be suitable as long as the results are consistently 1304 deterministic. The important results from the steps in this section 1305 are the transportDomain, the transportAddress, the wholeMessage, the 1306 wholeMessageLength, and a unique implementation-dependent session 1307 identifier. 1309 This procedure assumes that upon session establishment, an entry in a 1310 local transport mapping table is created in the Transport Model's 1311 LCD. This transport mapping table entry should be able to map a 1312 unique combination of the remote address, remote port number, local 1313 address and local port number to a implementation-dependent 1314 dtlsSessionID. 1316 1) The DTLS Transport Model examines the raw UDP message, in an 1317 implementation-dependent manner. If the message is not a DTLS 1318 message then it should be discarded. If the message is not a 1319 (D)TLS Application Data message then the message should be 1320 processed by the underlying DTLS framework as it is (for example) 1321 a session initialization or session modification message and no 1322 further steps below should be taken by the DTLS Transport. 1324 2) The DTLS Transport Model queries the LCD using the transport 1325 parameters to determine if a session already exists and its 1326 dtlsSessionID. As noted previously, the source and destination 1327 addresses and ports of the message should uniquely assign the 1328 message to a specific session identifier. However, another 1329 implementation-dependent method may be used if so desired. 1331 3) If a matching entry in the LCD does not exist then the message is 1332 discarded. Increment the dtlstmSessionNoAvailableSessions 1333 counter and stop processing the message. 1335 Note that an entry would already exist if the client and server's 1336 session establishment procedures had been successfully completed 1337 (as described both above and in Section 5.3) even if no message 1338 had yet been sent through the newly established session. An 1339 entry may not exist, however, if a "rogue" message was routed to 1340 the SNMP entity by mistake. An entry might also be missing 1341 because of a "broken" session (see operational considerations). 1343 4) Retrieve the dtlsSessionID from the LCD. 1345 5) The dtlsWholeMsg, and the dtlsSessionID are passed to DTLS for 1346 integrity checking and decryption using the dtlsRead() ASI. 1348 6) If the message fails integrity checks or other DTLS security 1349 processing then the dtlstmDTLSProtectionErrors counter is 1350 incremented, the message is discarded and processing of the 1351 message is stopped. 1353 7) The output of the dtlsRead results in an incomingMessage and an 1354 incomingMessageLength. These results and the dtlsSessionID are 1355 used below in the Section 5.1.2 to complete the processing of the 1356 incoming message. 1358 5.1.2. Transport Processing for Incoming Messages 1360 The procedures in this section describe how the DTLS Transport should 1361 process messages that have already been properly extracted from the 1362 DTLS stream, as described in Section 5.1.1. 1364 1) Create a tmStateReference cache for the subsequent reference and 1365 assign the following values within it: 1367 tmTransportDomain = snmpDTLSDomain 1369 tmTransportAddress = The address the message originated from, 1370 determined in an implementation dependent way. 1372 tmSecurityLevel = The derived tmSecurityLevel for the session, 1373 as discussed in Section 3.1.2 and Section 5.3. 1375 tmSecurityName = The derived tmSecurityName for the session as 1376 discussed in and Section 5.3. 1378 tmSessionID = The dtlsSessionID, which MUST be A unique session 1379 identifier for this DTLS session. The contents and format of 1380 this identifier are implementation dependent as long as it is 1381 unique to the session. A session identifier MUST NOT be 1382 reused until all references to it are no longer in use. The 1383 tmSessionID is equal to the dtlsSessionID discussed in 1384 Section 5.1.1. tmSessionID refers to the session identifier 1385 when stored in the tmStateReference and dtlsSessionID refers 1386 to the session identifier when stored in the LCD. They MUST 1387 always be equal when processing a given session's traffic. 1389 2) The wholeMessage and the wholeMessageLength are assigned values 1390 from the incomingMessage and incomingMessageLength values from 1391 the DTLS processing. 1393 3) The DTLS Transport Model passes the transportDomain, 1394 transportAddress, wholeMessage, and wholeMessageLength to the 1395 Dispatcher using the receiveMessage ASI: 1397 statusInformation = 1398 receiveMessage( 1399 IN transportDomain -- snmpSSHDomain 1400 IN transportAddress -- address for the received message 1401 IN wholeMessage -- the whole SNMP message from SSH 1402 IN wholeMessageLength -- the length of the SNMP message 1403 IN tmStateReference -- (NEW) transport info 1404 ) 1406 5.2. Procedures for an Outgoing Message 1408 The Dispatcher sends a message to the DTLS Transport Model using the 1409 following ASI: 1411 statusInformation = 1412 sendMessage( 1413 IN destTransportDomain -- transport domain to be used 1414 IN destTransportAddress -- transport address to be used 1415 IN outgoingMessage -- the message to send 1416 IN outgoingMessageLength -- its length 1417 IN tmStateReference -- (NEW) transport info 1418 ) 1420 This section describes the procedure followed by the DTLS Transport 1421 Model whenever it is requested through this ASI to send a message. 1423 1) Extract tmSessionID, tmTransportAddress, tmSecurityName, 1424 tmRequestedSecurityLevel. and tmSameSecurity from the 1425 tmStateReference. Note: The tmSessionID value may be undefined 1426 if session exists yet. 1428 2) If tmSameSecurity is true and either tmSessionID is undefined or 1429 refers to a session that is no longer open then increment the 1430 dtlstmSessionNoAvailableSessions counter, discard the message and 1431 return the error indication in the statusInformation. Processing 1432 of this message stops. 1434 3) If tmSameSecurity is false and tmSessionID refers to a session 1435 that is no longer available then an implementation SHOULD open a 1436 new session using the openSession() ASI as described below in 1437 step 3b. An implementation MAY choose to return an error to the 1438 calling module. 1440 4) If tmSessionID is undefined, then use tmTransportAddress, 1441 tmSecurityName and tmRequestedSecurityLevel to see if there is a 1442 corresponding entry in the LCD suitable to send the message over. 1444 3a) If there is a corresponding LCD entry, then this session 1445 will be used to send the message. 1447 3b) If there is not a corresponding LCD entry, then open a 1448 session using the openSession() ASI (discussed further in 1449 Section 4.4.1). Implementations MAY wish to offer message 1450 buffering to prevent redundant openSession() calls for the 1451 same cache entry. If an error is returned from 1452 OpenSession(), then discard the message, increment the 1453 dtlstmSessionOpenErrors, and return an error indication to 1454 the calling module. 1456 5) Using either the session indicated by the tmSessionID if there 1457 was one or the session resulting in the previous step, pass the 1458 outgoingMessage to DTLS for encapsulation and transmission. 1460 5.3. Establishing a Session 1462 The DTLS Transport Model provides the following primitive to 1463 establish a new DTLS session (previously discussed in Section 4.4.1): 1465 statusInformation = -- errorIndication or success 1466 openSession( 1467 IN destTransportDomain -- transport domain to be used 1468 IN destTransportAddress -- transport address to be used 1469 IN securityName -- on behalf of this principal 1470 IN securityLevel -- Level of Security requested 1471 OUT dtlsSessionID -- Session identifier for DTLS 1472 ) 1474 The following sections describe the procedures followed by a DTLS 1475 Transport Model when establishing a session as a Command Generator, a 1476 Notification Originator or as part of a Proxy Forwarder. 1478 The following describes the procedure to follow to establish a 1479 session between SNMP engines to exchange SNMP messages. This process 1480 is followed by any SNMP engine establishing a session for subsequent 1481 use. 1483 This MAY done automatically for SNMP messages which are not Response 1484 or Report messages. 1486 DTLS provides no explicit manner for transmitting an identity the 1487 client wishes to connect to during or prior to key exchange to 1488 facilitate certificate selection at the server (e.g. at a 1489 Notification Receiver). I.E., there is no available mechanism for 1490 sending notifications to a specific principal at a given UDP/port 1491 combination. Therefore, implementations MAY support responding with 1492 multiple identities using separate UDP port numbers to indicate the 1493 desired principal or some other implementation-dependent solution. 1495 1) The client selects the appropriate certificate and cipher_suites 1496 for the key agreement based on the tmSecurityName and the 1497 tmRequestedSecurityLevel for the session. For sessions being 1498 established as a result of a SNMP-TARGET-MIB based operation, the 1499 certificate will potentially have been identified via the 1500 dtlstmParamsTable mapping and the cipher_suites will have to be 1501 taken from system-wide or implementation-specific configuration. 1502 Otherwise, the certificate and appropriate cipher_suites will 1503 need to be passed to the openSession() ASI as supplemental 1504 information or configured through an implementation-dependent 1505 mechanism. It is also implementation-dependent and possibly 1506 policy-dependent how tmRequestedSecurityLevel will be used to 1507 influence the security capabilities provided by the DTLS session. 1508 However this is done, the security capabilities provided by DTLS 1509 MUST be at least as high as the level of security indicated by 1510 the tmRequestedSecurityLevel parameter. The actual security 1511 level of the session should be reported in the tmStateReference 1512 cache as tmSecurityLevel. For DTLS to provide strong 1513 authentication, each principal acting as a Command Generator 1514 SHOULD have its own certificate. 1516 2) Using the destTransportDomain and destTransportAddress values, 1517 the client will initiate the DTLS handshake protocol to establish 1518 session keys for message integrity and encryption. 1520 If the attempt to establish a session is unsuccessful, then 1521 dtlstmSessionOpenErrors is incremented, an error indication is 1522 returned, and session establishment processing stops. 1524 3) Once the secure session is established and both sides have been 1525 authenticated, certificate validation and identity expectations 1526 are performed. 1528 a) The DTLS server side of the connection identifies the 1529 authenticated identity from the DTLS client's principal 1530 certificate using the dtlstmCertificateToSNTable mapping 1531 table and records this in the tmStateReference cache as 1532 tmSecurityName. The details of the lookup process are fully 1533 described in the DESCRIPTION clause of the 1534 dtlstmCertificateToSNTable MIB object. If this verification 1535 fails in any way (for example because of failures in 1536 cryptographic verification or the lack of an appropriate row 1537 in the dtlstmCertificateToSNTable) then the session 1538 establishment MUST fail, the 1539 dtlstmSessionInvalidClientCertificates object is incremented 1540 and processing is stopped. 1542 b) The DTLS client side of the connection SHOULD verify that 1543 authenticated identity of the DTLS server's certificate is 1544 the expected identity and MUST do so if the client 1545 application is a Notification Generator. If strong 1546 authentication is desired then the DTLS server certificate 1547 MUST always be verified and checked against the expected 1548 identity. Methods for doing this are described in 1550 [I-D.hodges-server-ident-check]. DTLS provides assurance 1551 that the authenticated identity has been signed by a trusted 1552 configured certificate authority. If verification of the 1553 server's certificate fails in any way (for example because of 1554 failures in cryptographic verification or the presented 1555 identity was not the expected identity) then the session 1556 establishment MUST fail, the 1557 dtlstmSessionInvalidServerCertificates object is incremented 1558 and processing is stopped. 1560 4) The DTLS-specific session identifier is passed to the DTLS 1561 Transport Model and associated with the tmStateReference cache 1562 entry to indicate that the session has been established 1563 successfully and to point to a specific DTLS session for future 1564 use. 1566 5.4. Closing a Session 1568 The DTLS Transport Model provides the following primitive to close a 1569 session: 1571 statusInformation = 1572 closeSession( 1573 IN tmStateReference -- transport info 1574 ) 1576 The following describes the procedure to follow to close a session 1577 between a client and server. This process is followed by any SNMP 1578 engine closing the corresponding SNMP session. 1580 1) Look up the session in the cache and the LCD using the 1581 tmStateReference. 1583 2) If there is no session open associated with the tmStateReference, 1584 then closeSession processing is completed. 1586 3) Delete the entry from the cache and any other implementation- 1587 dependent information in the LCD. 1589 4) Have DTLS close the specified session. This SHOULD include 1590 sending a close_notify TLS Alert to inform the other side that 1591 session cleanup may be performed. 1593 6. MIB Module Overview 1595 This MIB module provides management of the DTLS Transport Model. It 1596 defines needed textual conventions, statistical counters and 1597 configuration infrastructure necessary for session establishment. 1598 Example usage of the configuration tables can be found in Appendix A. 1600 6.1. Structure of the MIB Module 1602 Objects in this MIB module are arranged into subtrees. Each subtree 1603 is organized as a set of related objects. The overall structure and 1604 assignment of objects to their subtrees, and the intended purpose of 1605 each subtree, is shown below. 1607 6.2. Textual Conventions 1609 Generic and Common Textual Conventions used in this module can be 1610 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1612 This module defines two new Textual Conventions: a new 1613 TransportDomain and TransportAddress format for describing DTLS 1614 connection addressing requirements. 1616 6.3. Statistical Counters 1618 The DTLSTM-MIB defines some statical counters that can provide 1619 network managers with feedback about DTLS session usage and potential 1620 errors that a MIB-instrumented device may be experiencing. 1622 6.4. Configuration Tables 1624 The DTLSTM-MIB defines configuration tables that a manager can use 1625 for help in configuring a MIB-instrumented device for sending and 1626 receiving SNMP messages over DTLS. In particular, there is a MIB 1627 table that extends the SNMP-TARGET-MIB for configuring certificates 1628 to be used and a MIB table for mapping incoming DTLS client 1629 certificates to securityNames. 1631 6.5. Relationship to Other MIB Modules 1633 Some management objects defined in other MIB modules are applicable 1634 to an entity implementing the DTLS Transport Model. In particular, 1635 it is assumed that an entity implementing the DTLSTM-MIB will 1636 implement the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], 1637 the SNMP-TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] 1638 and the SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1640 This MIB module is for managing DTLS Transport Model information. 1642 6.5.1. MIB Modules Required for IMPORTS 1644 The following MIB module imports items from SNMPV2-SMI [RFC2578], 1645 SNMPV2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1646 [RFC3413] and SNMP-CONF [RFC2580]. 1648 7. MIB Module Definition 1650 DTLSTM-MIB DEFINITIONS ::= BEGIN 1652 IMPORTS 1653 MODULE-IDENTITY, OBJECT-TYPE, 1654 OBJECT-IDENTITY, snmpModules, snmpDomains, 1655 Counter32, Unsigned32 1656 FROM SNMPv2-SMI 1657 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType 1658 FROM SNMPv2-TC 1659 MODULE-COMPLIANCE, OBJECT-GROUP 1660 FROM SNMPv2-CONF 1661 SnmpAdminString 1662 FROM SNMP-FRAMEWORK-MIB 1663 snmpTargetParamsEntry 1664 FROM SNMP-TARGET-MIB 1665 ; 1667 dtlstmMIB MODULE-IDENTITY 1668 LAST-UPDATED "200807070000Z" 1669 ORGANIZATION " " 1670 CONTACT-INFO "WG-EMail: 1671 Subscribe: 1673 Chairs: 1674 Co-editors: 1675 " 1677 DESCRIPTION "The DTLS Transport Model MIB 1679 Copyright (C) The IETF Trust (2008). This 1680 version of this MIB module is part of RFC XXXX; 1681 see the RFC itself for full legal notices." 1682 -- NOTE to RFC editor: replace XXXX with actual RFC number 1683 -- for this document and remove this note 1685 REVISION "200807070000Z" 1686 DESCRIPTION "The initial version, published in RFC XXXX." 1687 -- NOTE to RFC editor: replace XXXX with actual RFC number 1688 -- for this document and remove this note 1690 ::= { snmpModules xxxx } 1691 -- RFC Ed.: replace xxxx with IANA-assigned number and 1692 -- remove this note 1694 -- ************************************************ 1695 -- subtrees of the SNMP-DTLS-TM-MIB 1696 -- ************************************************ 1698 dtlstmNotifications OBJECT IDENTIFIER ::= { dtlstmMIB 0 } 1699 dtlstmObjects OBJECT IDENTIFIER ::= { dtlstmMIB 1 } 1700 dtlstmConformance OBJECT IDENTIFIER ::= { dtlstmMIB 2 } 1702 -- ************************************************ 1703 -- Objects 1704 -- ************************************************ 1706 snmpDTLSDomain OBJECT-IDENTITY 1707 STATUS current 1708 DESCRIPTION 1709 "The SNMP over DTLS transport domain. The corresponding 1710 transport address is of type SnmpDTLSAddress. 1712 When an SNMP entity uses the snmpDTLSDomain transport 1713 model, it must be capable of accepting messages up to 1714 the maximum MTU size for an interface it supports, minus the 1715 needed IP, UDP, DTLS and other protocol overheads. 1717 The securityName prefix to be associated with the 1718 snmpDTLSDomain is 'dtls'. This prefix may be used by 1719 security models or other components to identify what secure 1720 transport infrastructure authenticated a securityName." 1722 ::= { snmpDomains yy } 1724 -- RFC Ed.: Please replace the I-D reference with a proper one once it 1725 -- has been published. Note: xml2rfc doesn't handle refs within artwork 1727 -- RFC Ed.: replace yy with IANA-assigned number and 1728 -- remove this note 1730 -- RFC Ed.: replace 'dtls' with the actual IANA assigned prefix string 1731 -- if 'dtls' is not assigned to this document. 1733 SnmpDTLSAddress ::= TEXTUAL-CONVENTION 1734 DISPLAY-HINT "1a" 1735 STATUS current 1736 DESCRIPTION 1737 "Represents a UDP connection address for an IPv4 address, an 1738 IPv6 address or an ASCII encoded host name and port number. 1740 The hostname must be encoded in ASCII, as specified in RFC3490 1741 (Internationalizing Domain Names in Applications) followed by 1742 a colon ':' (ASCII character 0x3A) and a decimal port number 1743 in ASCII. The name SHOULD be fully qualified whenever 1744 possible. 1746 An IPv4 address must be a dotted decimal format followed by a 1747 colon ':' (ASCII character 0x3A) and a decimal port number in 1748 ASCII. 1750 An IPv6 address must be a colon separated format, surrounded 1751 by square brackets (ASCII characters 0x5B and 0x5D), followed 1752 by a colon ':' (ASCII character 0x3A) and a decimal port 1753 number in ASCII. 1755 Values of this textual convention may not be directly usable 1756 as transport-layer addressing information, and may require 1757 run-time resolution. As such, applications that write them 1758 must be prepared for handling errors if such values are not 1759 supported, or cannot be resolved (if resolution occurs at the 1760 time of the management operation). 1762 The DESCRIPTION clause of TransportAddress objects that may 1763 have snmpDTLSAddress values must fully describe how (and when) 1764 such names are to be resolved to IP addresses and vice versa. 1766 This textual convention SHOULD NOT be used directly in object 1767 definitions since it restricts addresses to a specific 1768 format. However, if it is used, it MAY be used either on its 1769 own or in conjunction with TransportAddressType or 1770 TransportDomain as a pair. 1772 When this textual convention is used as a syntax of an index 1773 object, there may be issues with the limit of 128 1774 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1775 that all MIB documents using this textual convention make 1776 explicit any limitations on index component lengths that 1777 management software must observe. This may be done either by 1778 including SIZE constraints on the index components or by 1779 specifying applicable constraints in the conceptual row 1780 DESCRIPTION clause or in the surrounding documentation." 1781 SYNTAX OCTET STRING (SIZE (1..255)) 1783 X509IdentifierHashType ::= TEXTUAL-CONVENTION 1784 STATUS current 1785 DESCRIPTION 1786 "Identifies a hashing algorithm type that will be used for 1787 identifying an X.509 certificate. 1789 The md5(1) value SHOULD NOT be used." 1790 SYNTAX INTEGER { md5(1), sha1(2), sha256(3) } 1792 X509IdentifierHash ::= TEXTUAL-CONVENTION 1793 STATUS current 1794 DESCRIPTION 1795 "A hash value that uniquely identifies a certificate within a 1796 systems local certificate store. The length of the value 1797 stored in an object of type X509IdentifierHash is dependent on 1798 the hashing algorithm that produced the hash. 1800 MIB structures making use of this textual convention should 1801 have an accompanying object of type X509IdentifierHashType. 1802 " 1803 SYNTAX OCTET STRING 1805 -- The dtlstmSession Group 1807 dtlstmSession OBJECT IDENTIFIER ::= { dtlstmObjects 1 } 1809 dtlstmSessionOpens OBJECT-TYPE 1810 SYNTAX Counter32 1811 MAX-ACCESS read-only 1812 STATUS current 1813 DESCRIPTION 1814 "The number of times an openSession() request has been 1815 executed as an SSH client, whether it succeeded or failed." 1816 ::= { dtlstmSession 1 } 1818 dtlstmSessionCloses OBJECT-TYPE 1819 SYNTAX Counter32 1820 MAX-ACCESS read-only 1821 STATUS current 1822 DESCRIPTION 1823 "The number of times a closeSession() request has been 1824 executed as an SSH client, whether it succeeded or failed." 1825 ::= { dtlstmSession 2 } 1827 dtlstmSessionOpenErrors OBJECT-TYPE 1828 SYNTAX Counter32 1829 MAX-ACCESS read-only 1830 STATUS current 1831 DESCRIPTION 1832 "The number of times an openSession() request failed to open a 1833 session as a SSH client, for any reason." 1834 ::= { dtlstmSession 3 } 1836 dtlstmSessionNoAvailableSessions OBJECT-TYPE 1837 SYNTAX Counter32 1838 MAX-ACCESS read-only 1839 STATUS current 1840 DESCRIPTION 1841 "The number of times an outgoing message was dropped because 1842 the session associated with the passed tmStateReference was no 1843 longer (or was never) available." 1844 ::= { dtlstmSession 4 } 1846 dtlstmSessionInvalidClientCertificates OBJECT-TYPE 1847 SYNTAX Counter32 1848 MAX-ACCESS read-only 1849 STATUS current 1850 DESCRIPTION 1851 "The number of times an incoming session was not established 1852 on an SSH server because the presented client certificate was 1853 invalid. Reasons for invalidation includes, but is not 1854 limited to, crypographic validation failures and lack of a 1855 suitable mapping row in the dtlstmCertificateToSNTable." 1856 ::= { dtlstmSession 5 } 1858 dtlstmSessionInvalidServerCertificates OBJECT-TYPE 1859 SYNTAX Counter32 1860 MAX-ACCESS read-only 1861 STATUS current 1862 DESCRIPTION 1863 "The number of times an outgoing session was not established 1864 on an SSH client because the presented server certificate was 1865 invalid. Reasons for invalidation includes, but is not 1866 limited to, crypographic validation failures and an unexpected 1867 presented certificate identity." 1868 ::= { dtlstmSession 6 } 1870 dtlstmDTLSProtectionErrors OBJECT-TYPE 1871 SYNTAX Counter32 1872 MAX-ACCESS read-only 1873 STATUS current 1874 DESCRIPTION 1875 "The number of times DTLS processing resulted in a message 1876 being discarded because it failed its integrity test, 1877 decryption processing or other DTLS processing." 1879 ::= { dtlstmSession 7 } 1881 -- Configuration Objects 1883 dtlstmConfig OBJECT IDENTIFIER ::= { dtlstmObjects 2 } 1885 -- Certificate mapping 1887 dtlstmCertificateMapping OBJECT IDENTIFIER ::= { dtlstmConfig 1 } 1889 dtlstmCertificateToSNCount OBJECT-TYPE 1890 SYNTAX Unsigned32 1891 MAX-ACCESS read-only 1892 STATUS current 1893 DESCRIPTION 1894 "A count of the number of entries in the 1895 dtlstmCertificateToSNTable" 1896 ::= { dtlstmCertificateMapping 1 } 1898 dtlstmCertificateToSNTableLastChanged OBJECT-TYPE 1899 SYNTAX TimeStamp 1900 MAX-ACCESS read-only 1901 STATUS current 1902 DESCRIPTION 1903 "The value of sysUpTime.0 when the dtlstmCertificateToSNTable 1904 was last modified through any means, or 0 if it has not been 1905 modified since the command responder was started." 1906 ::= { dtlstmCertificateMapping 2 } 1908 dtlstmCertificateToSNTable OBJECT-TYPE 1909 SYNTAX SEQUENCE OF DtlstmCertificateToSNEntry 1910 MAX-ACCESS not-accessible 1911 STATUS current 1912 DESCRIPTION 1913 "A table listing the X.509 certificates known to the entity 1914 and the associated method for determining the SNMPv3 security 1915 name from a certificate. 1917 On an incoming DTLS/SNMP connection the client's presented 1918 certificate should be examined and validated based on an 1919 established trusted CA certificate or self-signed public 1920 certificate. This table does not provide a mechanism for 1921 uploading the certificates as that is expected to occur 1922 through an out-of-band transfer. 1924 Once the authenticity of the certificate has been verified, 1925 this table can be consulted to determine the appropriate 1926 securityName to identify the remote connection. This is done 1927 by comparing the issuer's fingerprint hash type and value and 1928 the certificate's fingerprint hash type and value against the 1929 dtlstmCertHashType and dtlstmCertHashValue values in each 1930 entry of this table. If a matching entry is found then the 1931 securityName is selected based on the dtlstmCertMapType, 1932 dtlstmCertHashType, dtlstmCertHashValue and 1933 dtlstmCertSecurityName fields and the resulting securityName 1934 is used to identify the other side of the DTLS connection. 1936 This table should be treated as an ordered list of mapping 1937 rules to check. The first mapping rule appropriately matching 1938 a certificate in the local certificate store with a 1939 corresponding hash type (dtlstmCertHashType) and hash value 1940 (dtlstmCertHashValue) will be used to perform the mapping from 1941 X.509 certificate values to a securityName. If, after a 1942 matching row is found but the mapping can not succeed for some 1943 other reason then further attempts to perform the mapping MUST 1944 NOT be taken. For example, if the entry being checked 1945 contains a dtlstmCertMapType of bySubjectAltName(2) and an 1946 incoming connection uses a certificate with an issuer 1947 certificate matching the dtlstmCertHashType and 1948 dtlstmCertHashValue fields but the connecting certificate does 1949 not contain a subjectAltName field then the lookup operation 1950 must be treated as a failure. No further rows are examined for 1951 other potential mappings. 1953 Missing values of dtlstmCertID are acceptable and 1954 implementations should treat missing entries as a failed match 1955 and should continue to the next highest numbered row. E.G., 1956 the table may legally contain only two rows with dtlstmCertID 1957 values of 10 and 20. 1959 Users are encouraged to make use of certificates with 1960 subjectAltName fields that can be used as securityNames so 1961 that a single root CA certificate can allow all child 1962 certificate's subjectAltName to map directly to a securityName 1963 via a 1:1 transformation. However, this table is flexible 1964 enough to allow for situations where existing deployed 1965 certificate infrastructures do not provide adequate 1966 subjectAltName values for use as SNMPv3 securityNames. 1967 Certificates may also be mapped to securityNames using the 1968 CommonName portion of the Subject field which is also a 1969 scalable method of mapping certificate components to 1970 securityNames. Finally, direct mapping from each individual 1971 certificate fingerprint to a securityName is possible but 1972 requires one entry in the table per securityName." 1973 ::= { dtlstmCertificateMapping 3 } 1975 dtlstmCertificateToSNEntry OBJECT-TYPE 1976 SYNTAX DtlstmCertificateToSNEntry 1977 MAX-ACCESS not-accessible 1978 STATUS current 1979 DESCRIPTION 1980 "A row in the dtlstmCertificateToSNTable that specifies a 1981 mapping for an incoming DTLS certificate to a securityName to 1982 use for the connection." 1983 INDEX { dtlstmCertID } 1984 ::= { dtlstmCertificateToSNTable 1 } 1986 DtlstmCertificateToSNEntry ::= SEQUENCE { 1987 dtlstmCertID Unsigned32, 1988 dtlstmCertHashType X509IdentifierHashType, 1989 dtlstmCertHashValue X509IdentifierHash, 1990 dtlstmCertMapType INTEGER, 1991 dtlstmCertSecurityName SnmpAdminString, 1992 dtlstmCertStorageType StorageType, 1993 dtlstmCertRowStatus RowStatus 1994 } 1996 dtlstmCertID OBJECT-TYPE 1997 SYNTAX Unsigned32 1998 MAX-ACCESS not-accessible 1999 STATUS current 2000 DESCRIPTION 2001 "A unique arbitrary number index for a given certificate 2002 entry." 2003 ::= { dtlstmCertificateToSNEntry 1 } 2005 dtlstmCertHashType OBJECT-TYPE 2006 SYNTAX X509IdentifierHashType 2007 MAX-ACCESS read-create 2008 STATUS current 2009 DESCRIPTION 2010 "The hash algorithm to use when applying a hash to a X.509 2011 certificate for purposes of referring to it from the 2012 dtlstmCertHashValue column. 2014 The md5(1) value SHOULD NOT be used." 2015 DEFVAL { sha256 } 2016 ::= { dtlstmCertificateToSNEntry 2 } 2018 dtlstmCertHashValue OBJECT-TYPE 2019 SYNTAX X509IdentifierHash 2020 MAX-ACCESS read-create 2021 STATUS current 2022 DESCRIPTION 2023 "A cryptographic hash of a X.509 certificate. The use of this 2024 hash is dictated by the dtlstmCertMapType column. 2025 " 2026 ::= { dtlstmCertificateToSNEntry 3 } 2028 dtlstmCertMapType OBJECT-TYPE 2029 SYNTAX INTEGER { specified(1), bySubjectAltName(2), byCN(3) } 2030 MAX-ACCESS read-create 2031 STATUS current 2032 DESCRIPTION 2033 "The mapping type used to obtain the securityName from the 2034 certificate. The possible values of use and their usage 2035 methods are defined as follows: 2037 specified(1): The securityName that should be used locally to 2038 identify the remote entity is directly specified 2039 in the dtlstmCertSecurityName column from this 2040 table. The dtlstmCertHashValue MUST refer to a 2041 X.509 client certificate that will be mapped 2042 directly to the securityName specified in the 2043 dtlstmCertSecurityName column. 2045 bySubjectAltName(2): 2046 The securityName that should be used locally to 2047 identify the remote entity should be taken from 2048 the subjectAltName portion of the X.509 2049 certificate. The dtlstmCertHashValue MUST refer 2050 to a trust anchor certificate that is 2051 responsible for issuing certificates with 2052 carefully controlled subjectAltName fields. 2054 byCN(3): The securityName that should be used locally to 2055 identify the remote entity should be taken from 2056 the CommonName portion of the Subject field from 2057 the X.509 certificate. The dtlstmCertHashValue 2058 MUST refer to a trust anchor certificate that is 2059 responsible for issuing certificates with 2060 carefully controlled CommonName fields." 2061 DEFVAL { specified } 2062 ::= { dtlstmCertificateToSNEntry 4 } 2064 dtlstmCertSecurityName OBJECT-TYPE 2065 SYNTAX SnmpAdminString (SIZE(0..32)) 2066 MAX-ACCESS read-create 2067 STATUS current 2068 DESCRIPTION 2069 "The securityName that the session should use if the 2070 dtlstmCertMapType is set to specified(1), otherwise the value 2071 in this column should be ignored. If dtlstmCertMapType is set 2072 to specifed(1) and this column contains a zero-length string 2073 (which is not a legal securityName value) this row is 2074 effectively disabled and the match will not be considered 2075 successful." 2076 DEFVAL { "" } 2077 ::= { dtlstmCertificateToSNEntry 5 } 2079 dtlstmCertStorageType OBJECT-TYPE 2080 SYNTAX StorageType 2081 MAX-ACCESS read-create 2082 STATUS current 2083 DESCRIPTION 2084 "The storage type for this conceptual row. Conceptual rows 2085 having the value 'permanent' need not allow write-access to 2086 any columnar objects in the row." 2087 DEFVAL { nonVolatile } 2088 ::= { dtlstmCertificateToSNEntry 6 } 2090 dtlstmCertRowStatus OBJECT-TYPE 2091 SYNTAX RowStatus 2092 MAX-ACCESS read-create 2093 STATUS current 2094 DESCRIPTION 2095 "The status of this conceptual row. This object may be used 2096 to create or remove rows from this table. 2098 The value of this object has no effect on whether 2099 other objects in this conceptual row can be modified." 2100 ::= { dtlstmCertificateToSNEntry 7 } 2102 -- Maps securityNames to certificates for use by the SNMP-TARGET-MIB 2104 dtlstmParamsCount OBJECT-TYPE 2105 SYNTAX Unsigned32 2106 MAX-ACCESS read-only 2107 STATUS current 2108 DESCRIPTION 2109 "A count of the number of entries in the 2110 dtlstmParamsTable" 2111 ::= { dtlstmCertificateMapping 4 } 2113 dtlstmParamsTableLastChanged OBJECT-TYPE 2114 SYNTAX TimeStamp 2115 MAX-ACCESS read-only 2116 STATUS current 2117 DESCRIPTION 2118 "The value of sysUpTime.0 when the dtlstmParamsTable 2119 was last modified through any means, or 0 if it has not been 2120 modified since the command responder was started." 2121 ::= { dtlstmCertificateMapping 5 } 2123 dtlstmParamsTable OBJECT-TYPE 2124 SYNTAX SEQUENCE OF DtlstmParamsEntry 2125 MAX-ACCESS not-accessible 2126 STATUS current 2127 DESCRIPTION 2128 "This table augments the SNMP-TARGET-MIB's 2129 snmpTargetParamsTable with additional a DTLS client-side 2130 certificate certificate identifier to use when establishing 2131 new DTLS connections." 2132 ::= { dtlstmCertificateMapping 6 } 2134 dtlstmParamsEntry OBJECT-TYPE 2135 SYNTAX DtlstmParamsEntry 2136 MAX-ACCESS not-accessible 2137 STATUS current 2138 DESCRIPTION 2139 "A conceptual row containing a locally held certificate's hash 2140 type and hash value for a given snmpTargetParamsEntry. The 2141 values in this row should be ignored if not the connection 2142 that needs to be established, as indicated by the 2143 SNMP-TARGET-MIB infrastructure, is not a DTLS based 2144 connection." 2145 AUGMENTS { snmpTargetParamsEntry } 2146 ::= { dtlstmParamsTable 1 } 2148 DtlstmParamsEntry ::= SEQUENCE { 2149 dtlstmParamsHashType X509IdentifierHashType, 2150 dtlstmParamsHashValue X509IdentifierHash, 2151 dtlstmParamsStorageType StorageType, 2152 dtlstmParamsRowStatus RowStatus 2153 } 2155 dtlstmParamsHashType OBJECT-TYPE 2156 SYNTAX X509IdentifierHashType 2157 MAX-ACCESS read-create 2158 STATUS current 2159 DESCRIPTION 2160 "The hash algorithm type for the hash stored in the 2161 dtlstmParamsHash column to identify a locally-held X.509 2162 certificate that should be used when initiating a DTLS 2163 connection as a DTLS client." 2164 DEFVAL { sha256 } 2165 ::= { dtlstmParamsEntry 1 } 2167 dtlstmParamsHashValue OBJECT-TYPE 2168 SYNTAX X509IdentifierHash 2169 MAX-ACCESS read-create 2170 STATUS current 2171 DESCRIPTION 2172 "A cryptographic hash of a X.509 certificate. This object 2173 should store the hash of a locally held X.509 certificate that 2174 should be used when initiating a DTLS connection as a DTLS 2175 client." 2176 ::= { dtlstmParamsEntry 2 } 2178 dtlstmParamsStorageType OBJECT-TYPE 2179 SYNTAX StorageType 2180 MAX-ACCESS read-create 2181 STATUS current 2182 DESCRIPTION 2183 "The storage type for this conceptual row. Conceptual rows 2184 having the value 'permanent' need not allow write-access to 2185 any columnar objects in the row." 2186 DEFVAL { nonVolatile } 2187 ::= { dtlstmParamsEntry 3 } 2189 dtlstmParamsRowStatus OBJECT-TYPE 2190 SYNTAX RowStatus 2191 MAX-ACCESS read-create 2192 STATUS current 2193 DESCRIPTION 2194 "The status of this conceptual row. This object may be used 2195 to create or remove rows from this table. 2197 The value of this object has no effect on whether 2198 other objects in this conceptual row can be modified." 2199 ::= { dtlstmParamsEntry 4 } 2201 -- ************************************************ 2202 -- dtlstmMIB - Conformance Information 2203 -- ************************************************ 2205 dtlstmCompliances OBJECT IDENTIFIER ::= { dtlstmConformance 1 } 2207 dtlstmGroups OBJECT IDENTIFIER ::= { dtlstmConformance 2 } 2209 -- ************************************************ 2210 -- Compliance statements 2211 -- ************************************************ 2213 dtlstmCompliance MODULE-COMPLIANCE 2214 STATUS current 2215 DESCRIPTION 2216 "The compliance statement for SNMP engines that support the 2217 SNMP-DTLS-TM-MIB" 2218 MODULE 2219 MANDATORY-GROUPS { dtlstmStatsGroup, 2220 dtlstmIncomingGroup, dtlstmOutgoingGroup } 2221 ::= { dtlstmCompliances 1 } 2223 -- ************************************************ 2224 -- Units of conformance 2225 -- ************************************************ 2226 dtlstmStatsGroup OBJECT-GROUP 2227 OBJECTS { 2228 dtlstmSessionOpens, 2229 dtlstmSessionCloses, 2230 dtlstmSessionOpenErrors, 2231 dtlstmSessionNoAvailableSessions, 2232 dtlstmSessionInvalidClientCertificates, 2233 dtlstmSessionInvalidServerCertificates, 2234 dtlstmDTLSProtectionErrors 2235 } 2236 STATUS current 2237 DESCRIPTION 2238 "A collection of objects for maintaining 2239 statistical information of an SNMP engine which 2240 implements the SNMP DTLS Transport Model." 2241 ::= { dtlstmGroups 1 } 2243 dtlstmIncomingGroup OBJECT-GROUP 2244 OBJECTS { 2245 dtlstmCertificateToSNCount, 2246 dtlstmCertificateToSNTableLastChanged, 2247 dtlstmCertHashType, 2248 dtlstmCertHashValue, 2249 dtlstmCertMapType, 2250 dtlstmCertSecurityName, 2251 dtlstmCertStorageType, 2252 dtlstmCertRowStatus 2253 } 2254 STATUS current 2255 DESCRIPTION 2256 "A collection of objects for maintaining 2257 incoming connection certificate mappings to 2258 securityNames of an SNMP engine which implements the 2259 SNMP DTLS Transport Model." 2260 ::= { dtlstmGroups 2 } 2262 dtlstmOutgoingGroup OBJECT-GROUP 2263 OBJECTS { 2264 dtlstmParamsCount, 2265 dtlstmParamsTableLastChanged, 2266 dtlstmParamsHashType, 2267 dtlstmParamsHashValue, 2268 dtlstmParamsStorageType, 2269 dtlstmParamsRowStatus 2270 } 2271 STATUS current 2272 DESCRIPTION 2273 "A collection of objects for maintaining 2274 outgoing connection certificates to use when opening 2275 connections as a result of SNMP-TARGET-MIB settings." 2276 ::= { dtlstmGroups 3 } 2278 END 2280 8. Operational Considerations 2282 This section discusses various operational aspects of the solution 2284 8.1. Sessions 2286 A session is discussed throughout this document as meaning a security 2287 association between the DTLS client and the DTLS server. State 2288 information for the sessions are maintained in each DTLSTM and this 2289 information is created and destroyed as sessions are opened and 2290 closed. Because of the connectionless nature of UDP, a "broken" 2291 session, one side up one side down, could result if one side of a 2292 session is brought down abruptly (i.e., reboot, power outage, etc.). 2293 Whenever possible, implementations SHOULD provide graceful session 2294 termination through the use of disconnect messages. Implementations 2295 SHOULD also have a system in place for dealing with "broken" 2296 sessions. Implementations SHOULD support the session resumption 2297 feature of TLS. 2299 To simplify session management it is RECOMMENDED that implementations 2300 utilize two separate ports, one for Notification sessions and one for 2301 Command sessions. If this implementation recommendation is followed, 2302 DTLS clients will always send REQUEST messages and DTLS servers will 2303 always send RESPONSE messages. With this assertion, implementations 2304 may be able to simplify "broken" session handling, session 2305 resumption, and other aspects of session management such as 2306 guaranteeing that Request- Response pairs use the same session. 2308 Depending on the algorithms used for generation of the master session 2309 secret, the privacy and integrity algorithms used to protect 2310 messages, the environment of the session, the amount of data 2311 transferred, and the sensitivity of the data, a time-to-live (TTL) 2312 value SHOULD be established for sessions. An upper limit of 24 hours 2313 is suggested for this TTL value. The TTL value could be stored in 2314 the LCD and checked before passing a message to the DTLS session. 2316 8.2. Notification Receiver Credential Selection 2318 When an SNMP engine needs to establish an outgoing session for 2319 notifications, the snmpTargetParamsTable includes an entry for the 2320 snmpTargetParamsSecurityName of the target. However, the receiving 2321 SNMP engine (Server) does not know which DTLS certificate to offer to 2322 the Client so that the tmSecurityName identity-authentication will be 2323 successful. The best solution would be to maintain a one-to-one 2324 mapping between certificates and incoming ports for notification 2325 receivers, although other implementation dependent mechanisms may be 2326 used instead. This can be handled at the Notification Originator by 2327 configuring the snmpTargetAddrTable (snmpTargetAddrTDomain and 2328 snmpTargetAddrTAddress) and then requiring the receiving SNMP engine 2329 to monitor multiple incoming static ports based on which principals 2330 are capable of receiving notifications. Implementations MAY also 2331 choose to designate a single Notification Receiver Principal to 2332 receive all incoming TRAPS and INFORMS. 2334 8.3. contextEngineID Discovery 2336 Because most Command Responders have contextEngineIDs that are 2337 identical to the USM securityEngineID, the USM provides Command 2338 Generators with the ability to discover a default contextEngineID to 2339 use. Because the DTLS transport does not make use of a discoverable 2340 securityEngineID like the USM does, it may be difficult for Command 2341 Generators to discover a suitable default contextEngineID. 2342 Implementations should consider offering another engineID discovery 2343 mechanism to continue providing Command Generators with a 2344 contextEngineID discovery mechanism. A recommended discovery 2345 solution is documented in [RFC5343]. 2347 9. Security Considerations 2349 This document describes a transport model that permits SNMP to 2350 utilize DTLS security services. The security threats and how the 2351 DTLS transport model mitigates these threats are covered in detail 2352 throughout this document. Security considerations for DTLS are 2353 covered in [RFC4347] and security considerations for TLS are 2354 described in Appendices D, E, and F of TLS 1.1 [RFC4346]. DTLS adds 2355 to the security considerations of TLS only because it is more 2356 vulnerable to denial of service attacks. A random cookie exchange 2357 was added to the handshake to prevent anonymous denial of service 2358 attacks. RFC 4347 recommends that the cookie exchange is utilized 2359 for all handshakes and therefore it is RECOMMENDED that implementers 2360 also support this cookie exchange. 2362 9.1. Certificates, Authentication, and Authorization 2364 Implementations are responsible for providing a security certificate 2365 configuration installation . Implementations SHOULD support 2366 certificate revocation lists and expiration of certificates or other 2367 access control mechanisms. 2369 DTLS provides for both authentication of the identity of the DTLS 2370 server and authentication of the identity of the DTLS client. Access 2371 to MIB objects for the authenticated principal MUST be enforced by an 2372 access control subsystem (e.g. the VACM). 2374 Authentication of the Command Generator principal's identity is 2375 important for use with the SNMP access control subsystem to ensure 2376 that only authorized principals have access to potentially sensitive 2377 data. The authenticated identity of the Command Generator 2378 principal's certificate is mapped to an SNMP model-independent 2379 securityName for use with SNMP access control, as discussed in 2380 Section 4.5.3.4, Section 7 and other sections. 2382 Furthermore, the DTLS handshake only provides assurance that the 2383 certificate of the authenticated identity has been signed by an 2384 configured accepted Certificate Authority. DTLS has no way to 2385 further authorize or reject access based on the authenticated 2386 identity. An Access Control Model (such as the VACM) provides access 2387 control and authorization of a Command Generator's requests to a 2388 Command Responder and a Notification Responder's authorization to 2389 receive Notifications from a Notification Originator. However to 2390 avoid man-in-the-middle attacks both ends of the DTLS based 2391 connection MUST check the certificate presented by the other side 2392 against what was expected. For example, Command Generators must 2393 check that the Command Responder presented and authenticated itself 2394 with a X.509 certificate that was expected. Not doing so would allow 2395 an impostor, at a minimum, to present false data, receive sensitive 2396 information and/or provide a false-positive belief that configuration 2397 was actually received and acted upon. Authenticating and verifying 2398 the identity of the DTLS server and the DTLS client for all 2399 operations ensures the authenticity of the SNMP engine that provides 2400 MIB data. 2402 The instructions found in the DESCRIPTION clause of the 2403 dtlstmCertificateToSNTable object must be followed exactly. 2404 Specifically, it is important that if a row matching a certificate or 2405 a certificate's issuer is found but the translation to a securityName 2406 using the row fails that the lookup process stops and no further rows 2407 are consulted. It is also important that the rows of the table be 2408 search in order starting with the row containing the lowest numbered 2409 dtlstmCertID value. 2411 9.2. Use with SNMPv1/SNMPv2c Messages 2413 The SNMPv1 and SNMPv2c message processing described in RFC3484 (BCP 2414 74) [RFC3584] always selects the SNMPv1(1) Security Model for an 2415 SNMPv1 message, or the SNMPv2c(2) Security Model for an SNMPv2c 2416 message. When running SNMPv1/SNMPv2c over a secure transport like 2417 the DTLS Transport Model, the securityName and securityLevel used for 2418 access control decisions are then derived from the community string, 2419 not the authenticated identity and securityLevel provided by the DTLS 2420 Transport Model. 2422 9.3. MIB Module Security 2424 The MIB objects in this document must be protected with an adequate 2425 level of at least integrity protection, especially those objects 2426 which are writable. Since knowledge of authorization rules and 2427 certificate usage mechanisms may be considered sensitive, protection 2428 from disclosure of the SNMP traffic via encryption is also highly 2429 recommended. 2431 SNMP versions prior to SNMPv3 did not include adequate security. 2432 Even if the network itself is secure (for example by using IPSec or 2433 DTLS) there is no control as to who on the secure network is allowed 2434 to access and GET/SET (read/change/create/delete) the objects in this 2435 MIB module. 2437 It is RECOMMENDED that implementers consider the security features as 2438 provided by the SNMPv3 framework (see section 8 of [RFC3410]), 2439 including full support for the USM (see [RFC3414]) and the DTLS 2440 Transport Model cryptographic mechanisms (for authentication and 2441 privacy). 2443 10. IANA Considerations 2445 IANA is requested to assign: 2447 1. a UDP port number in the range 1..1023 in the 2448 http://www.iana.org/assignments/port-numbers registry which will 2449 be the default port for SNMP over a DTLS Transport Model as 2450 defined in this document, 2452 2. a UDP port number in the range 1..1023 in the 2453 http://www.iana.org/assignments/port-numbers registry which will 2454 be the default port for SNMPTRAP over a DTLS Transport Model as 2455 defined in this document, 2457 3. an SMI number under snmpDomains for the snmpDTLSDomain object 2458 identifier, 2460 4. a SMI number under snmpModules, for the MIB module in this 2461 document, 2463 5. "dtls" as the corresponding prefix for the snmpDTLSDomain in the 2464 SNMP Transport Model registry; 2466 11. Acknowledgements 2468 This document closely follows and copies the Secure Shell Transport 2469 Model for SNMP defined by David Harrington and Joseph Salowey in 2470 [I-D.ietf-isms-secshell]. 2472 This work was supported in part by the United States Department of 2473 Defense. Large portions of this document are based on work by 2474 General Dynamics C4 Systems and the following individuals: Brian 2475 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2476 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2477 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2479 12. References 2481 12.1. Normative References 2483 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2484 Requirement Levels", BCP 14, RFC 2119, March 1997. 2486 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2487 Protocol", RFC 2522, March 1999. 2489 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2490 Schoenwaelder, Ed., "Structure of Management Information 2491 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2493 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2494 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2495 STD 58, RFC 2579, April 1999. 2497 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2498 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2499 April 1999. 2501 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2502 "Introduction and Applicability Statements for Internet- 2503 Standard Management Framework", RFC 3410, December 2002. 2505 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2506 Architecture for Describing Simple Network Management 2507 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2508 December 2002. 2510 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2511 Management Protocol (SNMP) Applications", STD 62, 2512 RFC 3413, December 2002. 2514 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2515 (USM) for version 3 of the Simple Network Management 2516 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2518 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2519 Access Control Model (VACM) for the Simple Network 2520 Management Protocol (SNMP)", STD 62, RFC 3415, 2521 December 2002. 2523 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2524 Simple Network Management Protocol (SNMP)", STD 62, 2525 RFC 3418, December 2002. 2527 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2528 "Coexistence between Version 1, Version 2, and Version 3 2529 of the Internet-standard Network Management Framework", 2530 BCP 74, RFC 3584, August 2003. 2532 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 2533 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 2535 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2536 Security", RFC 4347, April 2006. 2538 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2539 Housley, R., and W. Polk, "Internet X.509 Public Key 2540 Infrastructure Certificate and Certificate Revocation List 2541 (CRL) Profile", RFC 5280, May 2008. 2543 [I-D.ietf-isms-transport-security-model] 2544 Harington, D., "Transport Security Model for SNMP". 2546 [I-D.ietf-isms-tmsm] 2547 Harington, D. and J. Schoenwaelder, "Transport Subsystem 2548 for the Simple Network Management Protocol (SNMP)". 2550 [X509] Rivest, R., Shamir, A., and L. M. Adleman, "A Method for 2551 Obtaining Digital Signatures and Public-Key 2552 Cryptosystems". 2554 [AES] National Institute of Standards, "Specification for the 2555 Advanced Encryption Standard (AES)". 2557 [DES] National Institute of Standards, "American National 2558 Standard for Information Systems-Data Link Encryption". 2560 [DSS] National Institute of Standards, "Digital Signature 2561 Standard". 2563 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2564 Obtaining Digital Signatures and Public-Key 2565 Cryptosystems". 2567 12.2. Informative References 2569 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 2570 December 2005. 2572 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 2573 RFC 4303, December 2005. 2575 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2576 RFC 4306, December 2005. 2578 [I-D.ietf-isms-secshell] 2579 Harington, D. and J. Salowey, "Secure Shell Transport 2580 Model for SNMP". 2582 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2583 (SNMP) Context EngineID Discovery". 2585 [I-D.hodges-server-ident-check] 2586 Hodges, J. and B. Morgan, "Generic Server Identity Check". 2588 Appendix A. Target and Notificaton Configuration Example 2590 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2591 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2592 daunting task without an example to follow. The following section 2593 describes an example of what pieces must be in place to accomplish 2594 this configuration. 2596 The isAccessAllowed() ASI requires configuration to exist in the 2597 following SNMP-VIEW-BASED-ACM-MIB tables: 2599 vacmSecurityToGroupTable 2600 vacmAccessTable 2601 vacmViewTreeFamilyTable 2603 The only table that needs to be discussed as particularly different 2604 here is the vacmSecurityToGroupTable. This table is indexed by both 2605 the SNMPv3 security model and the security name. The security model, 2606 when DTLSTM is in use, should be set to the value of XXX 2607 corresponding to the TSM [I-D.ietf-isms-transport-security-model]. 2608 An example vacmSecurityToGroupTable row might be filled out as 2609 follows (using a single SNMP SET request): 2611 Note to RFC editor: replace XXX in the previous paragraph above with 2612 the actual IANA-assigned number for the TSM security model and remove 2613 this note. 2615 vacmSecurityModel = XXX (TSM) 2616 vacmSecurityName = "blueberry" 2617 vacmGroupaName = "administrators" 2618 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2619 vacmSecurityToGroupStatus = 4 (createAndGo) 2621 Note to RFC editor: replace XXX in the vacmSecurityModel line above 2622 with the actual IANA-assigned number for the TSM security model and 2623 remove this note. 2625 This example will assume that the "administrators" group has been 2626 given proper permissions via rows in the vacmAccessTable and 2627 vacmViewTreeFamilyTable. 2629 Depending on whether this VACM configuration is for a Command 2630 Responder or a Command Generator the security name "blueberry" will 2631 come from a few different locations. 2633 For Notification Generator's performing authorization checks, the 2634 server's certificate must be verified against the expected 2635 certificate before proceeding to send the notification. The 2636 securityName be set by the SNMP-TARGET-MIB's 2637 snmpTargetParamsSecurityName column or other configuration mechanism 2638 and the certificate to use would be taken from the appropriate entry 2639 in the dtlstmParamsTable. The dtlstmParamsTable augments the SNMP- 2640 TARGET-MIB's snmpTargetParamsTable with client-side certificate 2641 information. 2643 For Command Responder applications, the vacmSecurityName "blueberry" 2644 value is a value that needs to come from an incoming DTLS session. 2645 The mapping from a recevied DTLS client certificate to a securityName 2646 is done with the dtlstmCertificateToSNTable. The certificates must 2647 be loaded into the device so that a dtlstmCertificateToSNEntry may 2648 refer to it. As an example, consider the following entry which will 2649 provide a mapping from a X.509's hash fingerprint directly to the 2650 "blueberry" securityName: 2652 dtlstmCertID = 1 (arbitrarily chosen) 2653 dtlstmCertHashType = sha256 2654 dtlstmCertHashValue = (appropriate sha256 fingerprint) 2655 dtlstmCertMapType = specified(1) 2656 dtlstmCertSecurityName = "blueberry" 2657 dtlstmCertStorageType = 3 (nonVolatile) 2658 dtlstmCertRowStatus = 4 (createAndGo) 2660 The above is an example of how to map a particular certificate to a 2661 particular securityName. It is recommended that users make use of 2662 direct subjectAltName or CommonName mappings where possible since it 2663 will provide a more scalable approach to certificate management. 2664 This entry provides an example of using a subjectAltName mapping: 2666 dtlstmCertID = 1 (arbitrarily chosen) 2667 dtlstmCertHashType = sha256 2668 dtlstmCertHashValue = (appropriate sha256 fingerprint) 2669 dtlstmCertMapType = bySubjectAltName(2) 2670 dtlstmCertStorageType = 3 (nonVolatile) 2671 dtlstmCertRowStatus = 4 (createAndGo) 2673 The above entry indicates the subjectAltName field for certificates 2674 created by an Issuing certificate with a corresponding hash type and 2675 value will be trusted to always produce common names that are 2676 directly 1 to 1 mappable into SNMPv3 securityNames. This type of 2677 configuration should only be used when the certificate authorities 2678 naming conventions are carefully controlled. 2680 For the example, if the incoming DTLS client provided certificate 2681 contained a subjectAltName of "blueberry" and the certificate was 2682 signed by a certificate matching the dtlstmCertHashType and 2683 dtlstmCertHashValue values above and the CA's certificate was 2684 properly installed on the device then the CommonName of "blueberry" 2685 would be used as the securityName for the session. 2687 Author's Address 2689 Wes Hardaker 2690 Sparta, Inc. 2691 P.O. Box 382 2692 Davis, CA 95617 2693 US 2695 Phone: +1 530 792 1913 2696 Email: ietf@hardakers.net 2698 Full Copyright Statement 2700 Copyright (C) The IETF Trust (2008). 2702 This document is subject to the rights, licenses and restrictions 2703 contained in BCP 78, and except as set forth therein, the authors 2704 retain all their rights. 2706 This document and the information contained herein are provided on an 2707 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2708 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2709 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2710 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2711 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2712 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2714 Intellectual Property 2716 The IETF takes no position regarding the validity or scope of any 2717 Intellectual Property Rights or other rights that might be claimed to 2718 pertain to the implementation or use of the technology described in 2719 this document or the extent to which any license under such rights 2720 might or might not be available; nor does it represent that it has 2721 made any independent effort to identify any such rights. Information 2722 on the procedures with respect to rights in RFC documents can be 2723 found in BCP 78 and BCP 79. 2725 Copies of IPR disclosures made to the IETF Secretariat and any 2726 assurances of licenses to be made available, or the result of an 2727 attempt made to obtain a general license or permission for the use of 2728 such proprietary rights by implementers or users of this 2729 specification can be obtained from the IETF on-line IPR repository at 2730 http://www.ietf.org/ipr. 2732 The IETF invites any interested party to bring to its attention any 2733 copyrights, patents or patent applications, or other proprietary 2734 rights that may cover technology that may be required to implement 2735 this standard. Please address the information to the IETF at 2736 ietf-ipr@ietf.org.