idnits 2.17.1 draft-hardaker-isms-dtls-tm-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 438 has weird spacing: '...patcher v ...' -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 24, 2009) is 5413 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-isms-transport-security-model' -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-isms-tmsm' -- Possible downref: Non-RFC (?) normative reference: ref. 'X509' -- Obsolete informational reference (is this intentional?): RFC 4306 (Obsoleted by RFC 5996) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ISMS W. Hardaker 3 Internet-Draft Sparta, Inc. 4 Intended status: Standards Track June 24, 2009 5 Expires: December 26, 2009 7 Transport Layer Security Transport Model for SNMP 8 draft-hardaker-isms-dtls-tm-05.txt 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may contain material 14 from IETF Documents or IETF Contributions published or made publicly 15 available before November 10, 2008. The person(s) controlling the 16 copyright in some of this material may not have granted the IETF 17 Trust the right to allow modifications of such material outside the 18 IETF Standards Process. Without obtaining an adequate license from 19 the person(s) controlling the copyright in such materials, this 20 document may not be modified outside the IETF Standards Process, and 21 derivative works of it may not be created outside the IETF Standards 22 Process, except to format it for publication as an RFC or to 23 translate it into languages other than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on December 26, 2009. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This document describes a Transport Model for the Simple Network 57 Management Protocol (SNMP), that uses either the Transport Layer 58 Security protocol or the Datagram Transport Layer Security (DTLS) 59 protocol. The TLS and DTLS protocols provide authentication and 60 privacy services for SNMP applications. This document describes how 61 the TLS Transport Model (TLSTM) implements the needed features of a 62 SNMP Transport Subsystem to make this protection possible in an 63 interoperable way. 65 This transport model is designed to meet the security and operational 66 needs of network administrators. The TLS mode can make use of TCP's 67 improved support for larger packet sizes and the DTLS mode provides 68 potentially superior operation in environments where a connectionless 69 (e.g. UDP or SCTP) transport is preferred. Both TLS and DTLS 70 integrate well into existing public keying infrastructures. 72 This document also defines a portion of the Management Information 73 Base (MIB) for monitoring and managing the TLS Transport Model for 74 SNMP. 76 Table of Contents 78 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 79 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 7 80 2. The Datagram Transport Layer Security Protocol . . . . . . . . 8 81 2.1. The (D)TLS Record Protocol . . . . . . . . . . . . . . . . 8 82 2.2. The (D)TLS Handshake Protocol . . . . . . . . . . . . . . 9 83 2.3. SNMP requirements of (D)TLS . . . . . . . . . . . . . . . 10 84 3. How the TLSTM fits into the Transport Subsystem . . . . . . . 10 85 3.1. Security Capabilities of this Model . . . . . . . . . . . 12 86 3.1.1. Threats . . . . . . . . . . . . . . . . . . . . . . . 12 87 3.1.2. Message Protection . . . . . . . . . . . . . . . . . . 13 88 3.1.3. (D)TLS Sessions . . . . . . . . . . . . . . . . . . . 14 89 3.2. Security Parameter Passing . . . . . . . . . . . . . . . . 15 90 3.3. Notifications and Proxy . . . . . . . . . . . . . . . . . 15 91 4. Elements of the Model . . . . . . . . . . . . . . . . . . . . 16 92 4.1. Certificates . . . . . . . . . . . . . . . . . . . . . . . 16 93 4.1.1. The Certificate Infrastructure . . . . . . . . . . . . 16 94 4.1.2. Provisioning for the Certificate . . . . . . . . . . . 17 95 4.2. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 18 96 4.3. SNMP Services . . . . . . . . . . . . . . . . . . . . . . 19 97 4.3.1. SNMP Services for an Outgoing Message . . . . . . . . 19 98 4.3.2. SNMP Services for an Incoming Message . . . . . . . . 20 99 4.4. (D)TLS Services . . . . . . . . . . . . . . . . . . . . . 21 100 4.4.1. Services for Establishing a Session . . . . . . . . . 21 101 4.4.2. (D)TLS Services for an Incoming Message . . . . . . . 22 102 4.4.3. (D)TLS Services for an Outgoing Message . . . . . . . 23 103 4.5. Cached Information and References . . . . . . . . . . . . 24 104 4.5.1. TLS Transport Model Cached Information . . . . . . . . 24 105 5. Elements of Procedure . . . . . . . . . . . . . . . . . . . . 24 106 5.1. Procedures for an Incoming Message . . . . . . . . . . . . 25 107 5.1.1. DTLS Processing for Incoming Messages . . . . . . . . 25 108 5.1.2. Transport Processing for Incoming Messages . . . . . . 26 109 5.2. Procedures for an Outgoing Message . . . . . . . . . . . . 27 110 5.3. Establishing a Session . . . . . . . . . . . . . . . . . . 29 111 5.4. Closing a Session . . . . . . . . . . . . . . . . . . . . 31 112 6. MIB Module Overview . . . . . . . . . . . . . . . . . . . . . 31 113 6.1. Structure of the MIB Module . . . . . . . . . . . . . . . 32 114 6.2. Textual Conventions . . . . . . . . . . . . . . . . . . . 32 115 6.3. Statistical Counters . . . . . . . . . . . . . . . . . . . 32 116 6.4. Configuration Tables . . . . . . . . . . . . . . . . . . . 32 117 6.5. Relationship to Other MIB Modules . . . . . . . . . . . . 32 118 6.5.1. MIB Modules Required for IMPORTS . . . . . . . . . . . 33 119 7. MIB Module Definition . . . . . . . . . . . . . . . . . . . . 33 120 8. Operational Considerations . . . . . . . . . . . . . . . . . . 49 121 8.1. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 49 122 8.2. Notification Receiver Credential Selection . . . . . . . . 50 123 8.3. contextEngineID Discovery . . . . . . . . . . . . . . . . 50 125 9. Security Considerations . . . . . . . . . . . . . . . . . . . 50 126 9.1. Certificates, Authentication, and Authorization . . . . . 51 127 9.2. Use with SNMPv1/SNMPv2c Messages . . . . . . . . . . . . . 52 128 9.3. MIB Module Security . . . . . . . . . . . . . . . . . . . 52 129 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 130 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 54 131 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 54 132 12.1. Normative References . . . . . . . . . . . . . . . . . . . 54 133 12.2. Informative References . . . . . . . . . . . . . . . . . . 55 134 Appendix A. Target and Notificaton Configuration Example . . . . 56 135 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 58 137 1. Introduction 139 It is important to understand the modular SNMPv3 architecture as 140 defined by [RFC3411] and enhanced by the Transport Subsystem 141 [I-D.ietf-isms-tmsm]. It is also important to understand the 142 terminology of the SNMPv3 architecture in order to understand where 143 the Transport Model described in this document fits into the 144 architecture and how it interacts with the other architecture 145 subsystems. For a detailed overview of the documents that describe 146 the current Internet-Standard Management Framework, please refer to 147 Section 7 of [RFC3410]. 149 This document describes a Transport Model that makes use of the 150 Transport Layer Security (TLS) [RFC5246] and the Datagram Transport 151 Layer Security (DTLS) Protocol [RFC4347], within a transport 152 subsystem [I-D.ietf-isms-tmsm]. DTLS is the datagram variant of the 153 Transport Layer Security (TLS) protocol [RFC5246]. The Transport 154 Model in this document is referred to as the Transport Layer Security 155 Transport Model (TLSTM). TLS and DTLS take advantage of the X.509 156 public keying infrastructure [X509]. This transport model is 157 designed to meet the security and operational needs of network 158 administrators, operate in both environments where a connectionless 159 (e.g. UDP or SCTP) transport is preferred and in environments where 160 large quantities of data need to be sent (e.g. over a TCP based 161 stream). Both TLS and DTLS integrate well into existing public 162 keying infrastructures. 164 This document also specifies a portion of the Management Information 165 Base (MIB) to define objects for monitoring and managing the TLS 166 Transport Model for SNMP. 168 Managed objects are accessed via a virtual information store, termed 169 the Management Information Base or MIB. MIB objects are generally 170 accessed through the Simple Network Management Protocol (SNMP). 171 Objects in the MIB are defined using the mechanisms defined in the 172 Structure of Management Information (SMI). This memo specifies a MIB 173 module that is compliant to the SMIv2, which is described in STD 58, 174 RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579] and STD 58, RFC 2580 175 [RFC2580]. 177 The diagram shown below gives a conceptual overview of two SNMP 178 entities communicating using the TLS Transport Model. One entity 179 contains a Command Responder and Notification Originator application, 180 and the other a Command Generator and Notification Responder 181 application. It should be understood that this particular mix of 182 application types is an example only and other combinations are 183 equally as legitimate. 185 +----------------------------------------------------------------+ 186 | Network | 187 +----------------------------------------------------------------+ 188 ^ ^ ^ ^ 189 |Notifications |Commands |Commands |Notifications 190 +---|---------------------|--------+ +--|---------------|-------------+ 191 | V V | | V V | 192 | +------------+ +------------+ | | +-----------+ +----------+ | 193 | | (D)TLS | | (D)TLS | | | | (D)TLS | | (D)TLS | | 194 | | Service | | Service | | | | Service | | Service | | 195 | | (Client) | | (Server) | | | | (Client) | | (Server)| | 196 | +------------+ +------------+ | | +-----------+ +----------+ | 197 | ^ ^ | | ^ ^ | 198 | | | | | | | | 199 | +--+----------+ | | +-+--------------+ | 200 | +-----|---------+----+ | | +---|--------+----+ | 201 | | V |LCD | +-------+ | | | V |LCD | +--------+ | 202 | | +------+ +----+ | | | | | +------+ +----+ | | | 203 | | | DTLS | <---------->| Cache | | | | | DTLS | <---->| Cache | | 204 | | | TM | | | | | | | | TM | | | | | 205 | | +------+ | +-------+ | | | +------+ | +--------+ | 206 | |Transport Subsystem | ^ | | |Transport Sub. | ^ | 207 | +--------------------+ | | | +-----------------+ | | 208 | ^ +----+ | | ^ | | 209 | | | | | | | | 210 | v | | | V | | 211 | +-------+ +----------+ +-----+ | | | +-----+ +------+ +-----+ | | 212 | | | |Message | |Sec. | | | | | | | MP | |Sec. | | | 213 | | Disp. | |Processing| |Sub- | | | | |Disp.| | Sub- | |Sub- | | | 214 | | | |Subsystem | |sys. | | | | | | |system| |sys. | | | 215 | | | | | | | | | | | | | | | | | | 216 | | | | | |+---+| | | | | | | | |+---+| | | 217 | | | | +-----+ | || || | | | | | |+----+| || || | | 218 | | <--->|v3MP |<-->||TSM|<-+ | | | <-->|v3MP|<->|TSM|<-+ | 219 | | | | +-----+ | || || | | | | |+----+| || || | 220 | +-------+ | | |+---+| | | +-----+ | | |+---+| | 221 | ^ | | | | | | ^ | | | | | 222 | | +----------+ +-----+ | | | +------+ +-----+ | 223 | +-+------------+ | | +-+------------+ | 224 | ^ ^ | | ^ ^ | 225 | | | | | | | | 226 | v v | | V V | 227 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 228 | | COMMAND | | NOTIFICATION | | | | COMMAND | | NOTIFICATION | | 229 | | RESPONDER | | ORIGINATOR | | | | GENERATOR | | RESPONDER | | 230 | | application | | applications | | | |application| | application | | 231 | +-------------+ +--------------+ | | +-----------+ +--------------+ | 232 | SNMP entity | | SNMP entity | 233 +----------------------------------+ +--------------------------------+ 235 1.1. Conventions 237 For consistency with SNMP-related specifications, this document 238 favors terminology as defined in STD62 rather than favoring 239 terminology that is consistent with non-SNMP specifications. This is 240 consistent with the IESG decision to not require the SNMPv3 241 terminology be modified to match the usage of other non-SNMP 242 specifications when SNMPv3 was advanced to Full Standard. 244 Authentication in this document typically refers to the English 245 meaning of "serving to prove the authenticity of" the message, not 246 data source authentication or peer identity authentication. 248 Large portions of this document simultaneously refer to both TLS and 249 DTLS when discussing TLSTM components that function equally with 250 either protocol. "(D)TLS" is used in these places to indicate that 251 the statement applies to either or both protocols as appropriate. 252 When a distinction between the protocols is needed they are referred 253 to independently through the use of "TLS" or "DTLS". The Transport 254 Model, however, is named "TLS Transport Model" and refers not to the 255 TLS or DTLS protocol but to the standard defined in this document, 256 which includes support for both TLS and DTLS. 258 The terms "manager" and "agent" are not used in this document, 259 because in the RFC 3411 architecture [RFC3411], all SNMP entities 260 have the capability of acting in either manager or agent or in both 261 roles depending on the SNMP application types supported in the 262 implementation. Where distinction is required, the application names 263 of Command Generator, Command Responder, Notification Originator, 264 Notification Receiver, and Proxy Forwarder are used. See "SNMP 265 Applications" [RFC3413] for further information. 267 Throughout this document, the terms "client" and "server" are used to 268 refer to the two ends of the (D)TLS transport connection. The client 269 actively opens the (D)TLS connection, and the server passively 270 listens for the incoming (D)TLS connection. Either SNMP entity may 271 act as client or as server, as discussed further below. 273 The User-Based Security Model (USM) [RFC3414] is a mandatory-to- 274 implement Security Model in STD 62. While (D)TLS and USM frequently 275 refer to a user, the terminology preferred in RFC3411 [RFC3411] and 276 in this memo is "principal". A principal is the "who" on whose 277 behalf services are provided or processing takes place. A principal 278 can be, among other things, an individual acting in a particular 279 role; a set of individuals, with each acting in a particular role; an 280 application or a set of applications, or a combination of these 281 within an administrative domain. 283 Throughout this document, the term "session" is used to refer to a 284 secure association between two TLS Transport Models that permits the 285 transmission of one or more SNMP messages within the lifetime of the 286 session. 288 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 289 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 290 document are to be interpreted as described in [RFC2119]. 292 2. The Datagram Transport Layer Security Protocol 294 (D)TLS provides authentication, data message integrity, and privacy 295 at the transport layer. (See [RFC4347]) 297 The primary goals of the TLS Transport Model are to provide privacy, 298 source authentication and data integrity between two communicating 299 SNMP entities. The (D)TLS protocol is composed of two layers: the 300 (D)TLS Record Protocol and the (D)TLS Handshake Protocol. The 301 following sections provide an overview of these two layers. Please 302 refer to [RFC4347] for a complete description of the protocol. 303 Readers familiar with (D)TLS can skip Section 2 except for section 304 Section 2.3. 306 2.1. The (D)TLS Record Protocol 308 At the lowest layer, layered on top of the transport control protocol 309 or a datagram transport protocol (e.g. UDP or SCTP) is the (D)TLS 310 Record Protocol. 312 The (D)TLS Record Protocol provides security that has three basic 313 properties: 315 o The session can be confidential. Symmetric cryptography is used 316 for data encryption (e.g., AES [AES], DES [DES] etc.). The keys 317 for this symmetric encryption are generated uniquely for each 318 session and are based on a secret negotiated by another protocol 319 (such as the (D)TLS Handshake Protocol). The Record Protocol can 320 also be used without encryption. 322 o Messages can have data integrity. Message transport includes a 323 message integrity check using a keyed MAC. Secure hash functions 324 (e.g., SHA, MD5, etc.) are used for MAC computations. The Record 325 Protocol can operate without a MAC, but is generally only used in 326 this mode while another protocol is using the Record Protocol as a 327 transport for negotiating security parameters. 329 o Messages are protected against replay. (D)TLS uses explicit 330 sequence numbers and integrity checks. DTLS uses a sliding window 331 to protect against replay of messages within a session. 333 (D)TLS also provides protection against replay of entire sessions. 334 In a properly-implemented keying material exchange, both sides will 335 generate new random numbers for each exchange. This results in 336 different encryption and integrity keys for every session. 338 2.2. The (D)TLS Handshake Protocol 340 The (D)TLS Record Protocol is used for encapsulation of various 341 higher-level protocols. One such encapsulated protocol, the (D)TLS 342 Handshake Protocol, allows the server and client to authenticate each 343 other and to negotiate an integrity algorithm, an encryption 344 algorithm and cryptographic keys before the application protocol 345 transmits or receives its first octet of data. Only the (D)TLS 346 client can initiate the handshake protocol. The (D)TLS Handshake 347 Protocol provides security that has three basic properties: 349 o The peer's identity can be authenticated using asymmetric (public 350 key) cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This 351 authentication can be made optional, but is generally required by 352 at least one of the peers. 354 (D)TLS supports three authentication modes: authentication of both 355 the server and the client, server authentication with an 356 unauthenticated client, and total anonymity. For authentication 357 of both entities, each entity provides a valid certificate chain 358 leading to an acceptable certificate authority. Each entity is 359 responsible for verifying that the other's certificate is valid 360 and has not expired or been revoked. See 361 [I-D.saintandre-tls-server-id-check] for further details on 362 standardized processing when checking Server certificate 363 identities. 365 o The negotiation of a shared secret is secure: the negotiated 366 secret is unavailable to eavesdroppers, and for any authenticated 367 handshake the secret cannot be obtained, even by an attacker who 368 can place himself in the middle of the session. 370 o The negotiation is not vulnerable to malicious modification: it is 371 infeasible for an attacker to modify negotiation communication 372 without being detected by the parties to the communication. 374 o DTLS uses a stateless cookie exchange to protect against anonymous 375 denial of service attacks and has retransmission timers, sequence 376 numbers, and counters to handle message loss, reordering, and 377 fragmentation. 379 2.3. SNMP requirements of (D)TLS 381 To properly support the SNMP over TLS Transport Model, the (D)TLS 382 implementation requires the following: 384 o The TLS Transport Model SHOULD always use authentication of both 385 the server and the client. 387 o At a minimum the TLS Transport Model MUST support authentication 388 of the Command Generator principals to guarantee the authenticity 389 of the securityName. 391 o The TLS Transport Model SHOULD support the message encryption to 392 protect sensitive data from eavesdropping attacks. 394 3. How the TLSTM fits into the Transport Subsystem 396 A transport model is a component of the Transport Subsystem. The TLS 397 Transport Model thus fits between the underlying (D)TLS transport 398 layer and the message dispatcher [RFC3411] component of the SNMP 399 engine and the Transport Subsystem. 401 The TLS Transport Model will establish a session between itself and 402 the TLS Transport Model of another SNMP engine. The sending 403 transport model passes unprotected messages from the dispatcher to 404 (D)TLS to be protected, and the receiving transport model accepts 405 decrypted and authenticated/integrity-checked incoming messages from 406 (D)TLS and passes them to the dispatcher. 408 After a TLS Transport Model session is established, SNMP messages can 409 conceptually be sent through the session from one SNMP message 410 dispatcher to another SNMP message dispatcher. If multiple SNMP 411 messages are needed to be passed between two SNMP applications they 412 SHOULD be passed through the same session. A TLSTM implementation 413 engine MAY choose to close a (D)TLS session to conserve resources. 415 The TLS Transport Model of an SNMP engine will perform the 416 translation between (D)TLS-specific security parameters and SNMP- 417 specific, model-independent parameters. 419 The diagram below depicts where the TLS Transport Model fits into the 420 architecture described in RFC3411 and the Transport Subsystem: 422 +------------------------------+ 423 | Network | 424 +------------------------------+ 425 ^ ^ ^ 426 | | | 427 v v v 428 +-------------------------------------------------------------------+ 429 | +--------------------------------------------------+ | 430 | | Transport Subsystem | +--------+ | 431 | | +-----+ +-----+ +-------+ +-------+ | | | | 432 | | | UDP | | SSH | |(D)TLS | . . . | other |<--->| Cache | | 433 | | | | | TM | | TM | | | | | | | 434 | | +-----+ +-----+ +-------+ +-------+ | +--------+ | 435 | +--------------------------------------------------+ ^ | 436 | ^ | | 437 | | | | 438 | Dispatcher v | | 439 | +--------------+ +---------------------+ +----------------+ | | 440 | | Transport | | Message Processing | | Security | | | 441 | | Dispatch | | Subsystem | | Subsystem | | | 442 | | | | +------------+ | | +------------+ | | | 443 | | | | +->| v1MP |<--->| | USM | | | | 444 | | | | | +------------+ | | +------------+ | | | 445 | | | | | +------------+ | | +------------+ | | | 446 | | | | +->| v2cMP |<--->| | Transport | | | | 447 | | Message | | | +------------+ | | | Security |<--+ | 448 | | Dispatch <---->| +------------+ | | | Model | | | 449 | | | | +->| v3MP |<--->| +------------+ | | 450 | | | | | +------------+ | | +------------+ | | 451 | | PDU Dispatch | | | +------------+ | | | Other | | | 452 | +--------------+ | +->| otherMP |<--->| | Model(s) | | | 453 | ^ | +------------+ | | +------------+ | | 454 | | +---------------------+ +----------------+ | 455 | v | 456 | +-------+-------------------------+---------------+ | 457 | ^ ^ ^ | 458 | | | | | 459 | v v v | 460 | +-------------+ +---------+ +--------------+ +-------------+ | 461 | | COMMAND | | ACCESS | | NOTIFICATION | | PROXY | | 462 | | RESPONDER |<->| CONTROL |<->| ORIGINATOR | | FORWARDER | | 463 | | application | | | | applications | | application | | 464 | +-------------+ +---------+ +--------------+ +-------------+ | 465 | ^ ^ | 466 | | | | 467 | v v | 468 | +----------------------------------------------+ | 469 | | MIB instrumentation | SNMP entity | 470 +-------------------------------------------------------------------+ 472 3.1. Security Capabilities of this Model 474 3.1.1. Threats 476 The TLS Transport Model provides protection against the threats 477 identified by the RFC 3411 architecture [RFC3411]: 479 1. Modification of Information - The modification threat is the 480 danger that some unauthorized entity may alter in-transit SNMP 481 messages generated on behalf of an authorized principal in such a 482 way as to effect unauthorized management operations, including 483 falsifying the value of an object. 485 (D)TLS provides verification that the content of each received 486 message has not been modified during its transmission through the 487 network, data has not been altered or destroyed in an 488 unauthorized manner, and data sequences have not been altered to 489 an extent greater than can occur non-maliciously. 491 2. Masquerade - The masquerade threat is the danger that management 492 operations unauthorized for a given principal may be attempted by 493 assuming the identity of another principal that has the 494 appropriate authorizations. 496 The TLSTM provides for authentication of the Command Generator, 497 Command Responder, Notification Generator, Notification Responder 498 and Proxy Forwarder through the use of X.509 certificates. 500 The masquerade threat can be mitigated against by using an 501 appropriate Access Control Model (ACM) such as the View-based 502 Access Control Module (VACM) [RFC3415]. In addition, it is 503 important to authenticate and verify both the authenticated 504 identity of the (D)TLS client and the (D)TLS server to protect 505 against this threat. (See Section 9 for more detail.) 507 3. Message stream modification - The re-ordering, delay or replay of 508 messages can and does occur through the natural operation of many 509 connectionless transport services. The message stream 510 modification threat is the danger that messages may be 511 maliciously re-ordered, delayed or replayed to an extent which is 512 greater than can occur through the natural operation of 513 connectionless transport services, in order to effect 514 unauthorized management operations. 516 (D)TLS provides replay protection with a MAC that includes a 517 sequence number. Since UDP provides no sequencing ability DTLS 518 uses a sliding window protocol with the sequence number for 519 replay protection, see [RFC4347]. The technique used is similar 520 to that as in IPsec AH/ESP [RFC4302] [RFC4303], by maintaining a 521 bitmap window of received records. Records that are too old to 522 fit in the window and records that have previously been received 523 are silently discarded. The replay detection feature is 524 optional, since packet duplication can also occur naturally due 525 to routing errors and does not necessarily indicate an active 526 attack. Applications may conceivably detect duplicate packets 527 and accordingly modify their data transmission strategy. 529 4. Disclosure - The disclosure threat is the danger of eavesdropping 530 on the exchanges between SNMP engines. Protecting against this 531 threat may be required by local policy at the deployment site. 533 Symmetric cryptography (e.g., AES [AES], DES [DES] etc.) can be 534 used by (D)TLS for data privacy. The keys for this symmetric 535 encryption are generated uniquely for each session and are based 536 on a secret negotiated by another protocol (such as the (D)TLS 537 Handshake Protocol). 539 5. Denial of Service - the RFC 3411 architecture [RFC3411] states 540 that denial of service (DoS) attacks need not be addressed by an 541 SNMP security protocol. However, datagram-based security 542 protocols like DTLS are susceptible to a variety of denial of 543 service attacks because it is more vulnerable to spoofed 544 messages. 546 In order to counter both of these attacks, DTLS borrows the 547 stateless cookie technique used by Photuris [RFC2522] and IKEv2 548 [RFC4306] and is described fully in section 4.2.1 of [RFC4347]. 549 This mechanism, though, does not provide any defense against 550 denial of service attacks mounted from valid IP addresses. DTLS 551 Transport Model server implementations MUST support DTLS cookies. 553 Implementations are not required to perform the stateless cookie 554 exchange for every DTLS handshakes but in environments where 555 amplification could be an issue or has been detected it is 556 RECOMMENDED that the cookie exchange is utilized. 558 3.1.2. Message Protection 560 The RFC 3411 architecture recognizes three levels of security: 562 o without authentication and without privacy (noAuthNoPriv) 564 o with authentication but without privacy (authNoPriv) 566 o with authentication and with privacy (authPriv) 567 The TLS Transport Model determines from (D)TLS the identity of the 568 authenticated principal, and the type and address associated with an 569 incoming message, and the TLS Transport Model provides this 570 information to (D)TLS for an outgoing message. 572 When an application requests a session for a message, through the 573 cache, the application requests a security level for that session. 574 The TLS Transport Model MUST ensure that the (D)TLS session provides 575 security at least as high as the requested level of security. How 576 the security level is translated into the algorithms used to provide 577 data integrity and privacy is implementation-dependent. However, the 578 NULL integrity and encryption algorithms MUST NOT be used to fulfill 579 security level requests for authentication or privacy. 580 Implementations MAY choose to force (D)TLS to only allow 581 cipher_suites that provide both authentication and privacy to 582 guarantee this assertion. 584 If a suitable interface between the TLS Transport Model and the 585 (D)TLS Handshake Protocol is implemented to allow the selection of 586 security level dependent algorithms, for example a security level to 587 cipher_suites mapping table, then different security levels may be 588 utilized by the application. However, different port numbers will 589 need to be used by at least one side of the connection to 590 differentiate between the (D)TLS sessions. This is the only way to 591 ensured proper selection of a session ID for an incoming (D)TLS 592 message. 594 The authentication, integrity and privacy algorithms used by the 595 (D)TLS Protocol [RFC4347] may vary over time as the science of 596 cryptography continues to evolve and the development of (D)TLS 597 continues over time. Implementers are encouraged to plan for changes 598 in operator trust of particular algorithms and implementations should 599 offer configuration settings for mapping algorithms to SNMPv3 600 security levels. 602 3.1.3. (D)TLS Sessions 604 (D)TLS sessions are opened by the TLS Transport Model during the 605 elements of procedure for an outgoing SNMP message. Since the sender 606 of a message initiates the creation of a (D)TLS session if needed, 607 the (D)TLS session will already exist for an incoming message. 609 Implementations MAY choose to instantiate (D)TLS sessions in 610 anticipation of outgoing messages. This approach might be useful to 611 ensure that a (D)TLS session to a given target can be established 612 before it becomes important to send a message over the (D)TLS 613 session. Of course, there is no guarantee that a pre-established 614 session will still be valid when needed. 616 DTLS sessions, when used over UDP, are uniquely identified within the 617 TLS Transport Model by the combination of transportDomain, 618 transportAddress, securityName, and requestedSecurityLevel associated 619 with each session. Each unique combination of these parameters MUST 620 have a locally-chosen unique dtlsSessionID associated for active 621 sessions. For further information see Section 4.4 and Section 5. 622 TLS and DTLS over SCTP sessions, on the other hand, do not require a 623 unique paring of attributes since their lower layer protocols (TCP 624 and SCTP) already provide adequate session framing. 626 3.2. Security Parameter Passing 628 For the (D)TLS server-side, (D)TLS-specific security parameters 629 (i.e., cipher_suites, X.509 certificate fields, IP address and port) 630 are translated by the TLS Transport Model into security parameters 631 for the TLS Transport Model and security model (i.e., securityLevel, 632 securityName, transportDomain, transportAddress). The transport- 633 related and (D)TLS-security-related information, including the 634 authenticated identity, are stored in a cache referenced by 635 tmStateReference. 637 For the (D)TLS client-side, the TLS Transport Model takes input 638 provided by the dispatcher in the sendMessage() Abstract Service 639 Interface (ASI) and input from the tmStateReference cache. The 640 (D)TLS Transport Model converts that information into suitable 641 security parameters for (D)TLS and establishes sessions as needed. 643 The elements of procedure in Section 5 discuss these concepts in much 644 greater detail. 646 3.3. Notifications and Proxy 648 (D)TLS sessions may be initiated by (D)TLS clients on behalf of 649 command generators or notification originators. Command generators 650 are frequently operated by a human, but notification originators are 651 usually unmanned automated processes. The targets to whom 652 notifications should be sent is typically determined and configured 653 by a network administrator. 655 The SNMP-TARGET-MIB module [RFC3413] contains objects for defining 656 management targets, including transportDomain, transportAddress, 657 securityName, securityModel, and securityLevel parameters, for 658 Notification Generator, Proxy Forwarder, and SNMP-controllable 659 Command Generator applications. Transport domains and transport 660 addresses are configured in the snmpTargetAddrTable, and the 661 securityModel, securityName, and securityLevel parameters are 662 configured in the snmpTargetParamsTable. This document defines a MIB 663 module that extends the SNMP-TARGET-MIB's snmpTargetParamsTable to 664 specify a (D)TLS client-side certificate to use for the connection. 666 When configuring a (D)TLS target, the snmpTargetAddrTDomain and 667 snmpTargetAddrTAddress parameters in snmpTargetAddrTable should be 668 set to the snmpTLSDomain, snmpDTLSUDPDomain, or snmpDTLSSCTPDomain 669 object and an appropriate snmpTLSAddress, snmpDTLSUDPAddress or 670 snmpDTLSSCTPAddress value respectively. The snmpTargetParamsMPModel 671 column of the snmpTargetParamsTable should be set to a value of 3 to 672 indicate the SNMPv3 message processing model. The 673 snmpTargetParamsSecurityName should be set to an appropriate 674 securityName value and the tlstmParamsHashType and 675 tlstmParamsHashValue parameters of the tlstmParamsTable should be set 676 to values that refer to a locally held certificate to be used. Other 677 parameters, for example cryptographic configuration such as cipher 678 suites to use, must come from configuration mechanisms not defined in 679 this document. The other needed configuration may be configured 680 using SNMP or other implementation-dependent mechanisms (for example, 681 via a CLI). This securityName defined in the 682 snmpTargetParamsSecurityName column will be used by the access 683 control model to authorize any notifications that need to be sent. 685 4. Elements of the Model 687 This section contains definitions required to realize the (D)TLS 688 Transport Model defined by this document. Readers familiar with 689 X.509 certificates can skip this section until Section 4.1.2. 691 4.1. Certificates 693 (D)TLS makes use of X.509 certificates for authentication of both 694 sides of the transport. This section discusses the use of 695 certificates in (D)TLS and the its effects on SNMP over (D)TLS. 697 4.1.1. The Certificate Infrastructure 699 Users of a public key SHALL be confident that the associated private 700 key is owned by the correct remote subject (person or system) with 701 which an encryption or digital signature mechanism will be used. 702 This confidence is obtained through the use of public key 703 certificates, which are data structures that bind public key values 704 to subjects. The binding is asserted by having a trusted CA 705 digitally sign each certificate. The CA may base this assertion upon 706 technical means (i.e., proof of possession through a challenge- 707 response protocol), presentation of the private key, or on an 708 assertion by the subject. A certificate has a limited valid lifetime 709 which is indicated in its signed contents. Because a certificate's 710 signature and timeliness can be independently checked by a 711 certificate-using client, certificates can be distributed via 712 untrusted communications and server systems, and can be cached in 713 unsecured storage in certificate-using systems. 715 ITU-T X.509 (formerly CCITT X.509) or ISO/IEC/ITU 9594-8, which was 716 first published in 1988 as part of the X.500 Directory 717 recommendations, defines a standard certificate format [X509] which 718 is a certificate which binds a subject (principal) to a public key 719 value. This was later further documented in [RFC5280]. 721 A X.509 certificate is a sequence of three required fields: 723 tbsCertificate: The field contains the names of the subject and 724 issuer, a public key associated with the subject, a validity 725 period, and other associated information. This field may also 726 contain extension components. 728 signatureAlgorithm: The signatureAlgorithm field contains the 729 identifier for the cryptographic algorithm used by the certificate 730 authority (CA) to sign this certificate. 732 signatureValue: The signatureValue field contains a digital 733 signature computed upon the ASN.1 DER encoded tbsCertificate 734 field. The ASN.1 DER encoded tbsCertificate is used as the input 735 to the signature function. This signature value is then ASN.1 DER 736 encoded as a BIT STRING and included in the Certificate's 737 signature field. By generating this signature, a CA certifies the 738 validity of the information in the tbsCertificate field. In 739 particular, the CA certifies the binding between the public key 740 material and the subject of the certificate. 742 The basic X.509 authentication procedure is as follows: A system is 743 initialized with a number of root certificates that contain the 744 public keys of a number of trusted CAs. When a system receives a 745 X.509 certificate, signed by one of those CAs, the certificate has to 746 be verified. It first checks the signatureValue field by using the 747 public key of the corresponding trusted CA. Then it compares the 748 decrypted information with a digest of the tbsCertificate field. If 749 they match, then the subject in the tbsCertificate field is 750 authenticated. 752 4.1.2. Provisioning for the Certificate 754 Authentication using (D)TLS will require that SNMP entities are 755 provisioned with certificates, which are signed by trusted 756 certificate authorities. Furthermore, SNMP entities will most 757 commonly need to be provisioned with root certificates which 758 represent the list of trusted certificate authorities that an SNMP 759 entity can use for certificate verification. SNMP entities MAY also 760 be provisioned with a X.509 certificate revocation mechanism which 761 can be used to verify that a certificate has not been revoked. 763 The authenticated tmSecurityName of the principal is looked up using 764 the tlstmCertificateToSNTable. This table either: 766 o Maps a certificate's fingerprint hash type and value to a directly 767 specified tmSecurityName. 769 o Identifies a certificate issuer's fingerprint hash type and value 770 and allows child certificate's subjectAltName or CommonName to 771 directly used as the tmSecurityNome. 773 The certificate trust anchors, being either CA certificates or public 774 keys for use by self-signed certificates, must be installed through 775 an out of band trusted mechanism into the server and its authenticity 776 MUST be verified before access is granted. Implementations SHOULD 777 choose to discard any connections for which no potential 778 tlstmCertificateToSNTable mapping exists before performing 779 certificate verification to avoid expending computational resources 780 associated with certificate verification. 782 The typical enterprise configuration will map the "subjectAltName" 783 component of the tbsCertificate to the TLSTM specific tmSecurityName. 784 Thus, the authenticated identity can be obtained by the TLS Transport 785 Model by extracting the subjectAltName from the peer's certificate 786 and the receiving application will have an appropriate tmSecurityName 787 for use by components like an access control model. This setup 788 requires very little configuration: a single row in the 789 tlstmCertificateToSNTable referencing a certificate authority. 791 An example mapping setup can be found in Appendix A 793 This tmSecurityName may be later translated from a TLSTM specific 794 tmSecurityName to a SNMP engine securityName by the security model. 795 A security model, like the TSM security model, may perform an 796 identity mapping or a more complex mapping to derive the securityName 797 from the tmSecurityName offered by the TLS Transport Model. 799 4.2. Messages 801 As stated in Section 4.1.1 of [RFC4347], each DTLS record must fit 802 within a single DTLS datagram. The TLSTM SHOULD prohibit SNMP 803 messages from being sent that exceeds the maximum DTLS message size. 804 The TLSTM implementation SHOULD return an error when the DTLS message 805 size would be exceeded and the message won't be sent. 807 4.3. SNMP Services 809 This section describes the services provided by the (D)TLS Transport 810 Model with their inputs and outputs. The services are between the 811 Transport Model and the dispatcher. 813 The services are described as primitives of an abstract service 814 interface (ASI) and the inputs and outputs are described as abstract 815 data elements as they are passed in these abstract service 816 primitives. 818 4.3.1. SNMP Services for an Outgoing Message 820 The dispatcher passes the information to the TLS Transport Model 821 using the ASI defined in the transport subsystem: 823 statusInformation = 824 sendMessage( 825 IN destTransportDomain -- transport domain to be used 826 IN destTransportAddress -- transport address to be used 827 IN outgoingMessage -- the message to send 828 IN outgoingMessageLength -- its length 829 IN tmStateReference -- reference to transport state 830 ) 832 The abstract data elements passed as parameters in the abstract 833 service primitives are as follows: 835 statusInformation: An indication of whether the passing of the 836 message was successful. If not it is an indication of the 837 problem. 839 destTransportDomain: The transport domain for the associated 840 destTransportAddress. The Transport Model uses this parameter to 841 determine the transport type of the associated 842 destTransportAddress. This parameter may also be used by the 843 transport subsystem to route the message to the appropriate 844 Transport Model. This document specifies three TLS and DTLS based 845 Transport Domains for use: the snmpTLSDomain, the 846 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 848 destTransportAddress: The transport address of the destination TLS 849 Transport Model in a format specified by the SnmpTLSAddress, the 850 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTIONs. 852 outgoingMessage: The outgoing message to send to (D)TLS for 853 encapsulation. 855 outgoingMessageLength: The length of the outgoing message. 857 tmStateReference: A handle/reference to tmSecurityData to be used 858 when securing outgoing messages. 860 4.3.2. SNMP Services for an Incoming Message 862 The TLS Transport Model processes the received message from the 863 network using the (D)TLS service and then passes it to the dispatcher 864 using the following ASI: 866 statusInformation = 867 receiveMessage( 868 IN transportDomain -- origin transport domain 869 IN transportAddress -- origin transport address 870 IN incomingMessage -- the message received 871 IN incomingMessageLength -- its length 872 IN tmStateReference -- reference to transport state 873 ) 875 The abstract data elements passed as parameters in the abstract 876 service primitives are as follows: 878 statusInformation: An indication of whether the passing of the 879 message was successful. If not it is an indication of the 880 problem. 882 transportDomain: The transport domain for the associated 883 transportAddress. This document specifies three TLS and DTLS 884 based Transport Domains for use: the snmpTLSDomain, the 885 snmpDTLSUDPDomain and the snmpDTLSSCTPDomain. 887 transportAddress: The transport address of the source of the 888 received message in a format specified by the SnmpTLSAddress, the 889 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 891 incomingMessage: The whole SNMP message stripped of all (D)TLS 892 protection data. 894 incomingMessageLength: The length of the SNMP message after being 895 processed by (D)TLS. 897 tmStateReference: A handle/reference to tmSecurityData to be used by 898 the security model. 900 4.4. (D)TLS Services 902 This section describes the services provided by the (D)TLS Transport 903 Model with their inputs and outputs. These services are between the 904 TLS Transport Model and the (D)TLS transport layer. The following 905 sections describe services for establishing and closing a session and 906 for passing messages between the (D)TLS transport layer and the TLS 907 Transport Model. 909 4.4.1. Services for Establishing a Session 911 The TLS Transport Model provides the following ASI to describe the 912 data passed between the Transport Model and the (D)TLS transport 913 layer for session establishment. 915 statusInformation = -- errorIndication or success 916 openSession( 917 IN destTransportDomain -- transport domain to be used 918 IN destTransportAddress -- transport address to be used 919 IN securityName -- on behalf of this principal 920 IN securityLevel -- Level of Security requested 921 OUT tlsSessionID -- Session identifier for (D)TLS 922 ) 924 The abstract data elements passed as parameters in the abstract 925 service primitives are as follows: 927 statusInformation: An indication of whether the process was 928 successful or not. If not, then the status information will 929 include the error indication provided by (D)TLS. 931 destTransportDomain: The transport domain for the associated 932 destTransportAddress. The TLS Transport Model uses this parameter 933 to determine the transport type of the associated 934 destTransportAddress. This document specifies three TLS and DTLS 935 based Transport Domains for use: the snmpTLSDomain, the 936 snmpDTLSUDPDomain, and the snmpDTLSSCTPDomain. 938 destTransportAddress: The transport address of the destination TLS 939 Transport Model in a format specified by the SnmpTLSAddress, the 940 SnmpDTLSUDPAddress or the SnmpDTLSSCTPAddress TEXTUAL-CONVENTION. 942 securityName: The security name representing the principal on whose 943 behalf the message will be sent. 945 securityLevel: The level of security requested by the application. 947 dtlsSessionID: An implementation-dependent session identifier to 948 reference the specific (D)TLS session. 950 DTLS and UDP do not provide a session de-multiplexing mechanism and 951 it is possible that implementations will only be able to identify a 952 unique session based on a unique combination of source address, 953 destination address, source UDP port number and destination UDP port 954 number. Because of this, when establishing a new sessions 955 implementations MUST use a different UDP source port number for each 956 connection to a remote destination IP-address/port-number combination 957 to ensure the remote entity can properly disambiguate between 958 multiple sessions from a host to the same port on a server. TLS and 959 DTLS over SCTP provide session de-multiplexing so this restriction is 960 not needed for TLS or DTLS over SCTP implementations. 962 The procedural details for establishing a session are further 963 described in Section 5.3. 965 Upon completion of the process the TLS Transport Model returns status 966 information and, if the process was successful the dtlsSessionID. 967 Other implementation-dependent data from (D)TLS are also returned. 968 The dtlsSessionID is stored in an implementation- dependent manner 969 and tied to the tmSecurityData for future use of this session. 971 4.4.2. (D)TLS Services for an Incoming Message 973 When the TLS Transport Model invokes the (D)TLS record layer to 974 verify proper security for the incoming message, it must use the 975 following ASI: 977 statusInformation = -- errorIndication or success 978 tlsRead( 979 IN tlsSessionID -- Session identifier for (D)TLS 980 IN wholeTlsMsg -- as received on the wire 981 IN wholeTlsMsgLength -- length as received on the wire 982 OUT incomingMessage -- the whole SNMP message from (D)TLS 983 OUT incomingMessageLength -- the length of the SNMP message 984 ) 986 The abstract data elements passed as parameters in the abstract 987 service primitives are as follows: 989 statusInformation: An indication of whether the process was 990 successful or not. If not, then the status information will 991 include the error indication provided by (D)TLS. 993 tlsSessionID: An implementation-dependent session identifier to 994 reference the specific (D)TLS session. How the (D)TLS session ID 995 is obtained for each message is implementation-dependent. As an 996 implementation hint, for dtls over udp the TLS Transport Model can 997 examine incoming messages to determine the source IP address, 998 source port number, destination IP address, and destination port 999 number and use these values to look up the local tlsSessionID in 1000 the list of active sessions. 1002 wholeDtlsMsg: The whole message as received on the wire. 1004 wholeDtlsMsgLength: The length of the message as it was received on 1005 the wire. 1007 incomingMessage: The whole SNMP message stripped of all (D)TLS 1008 privacy and integrity data. 1010 incomingMessageLength: The length of the SNMP message stripped of 1011 all (D)TLS privacy and integrity data. 1013 4.4.3. (D)TLS Services for an Outgoing Message 1015 When the TLS Transport Model invokes the (D)TLS record layer to 1016 encapsulate and transmit a SNMP message, it must use the following 1017 ASI. 1019 statusInformation = -- errorIndication or success 1020 tlsWrite( 1021 IN tlsSessionID -- Session identifier for (D)TLS 1022 IN outgoingMessage -- the message to send 1023 IN outgoingMessageLength -- its length 1024 ) 1026 The abstract data elements passed as parameters in the abstract 1027 service primitives are as follows: 1029 statusInformation: An indication of whether the process was 1030 successful or not. If not, then the status information will 1031 include the error indication provided by (D)TLS. 1033 tlsSessionID: An implementation-dependent session identifier to 1034 reference the specific (D)TLS session that the message should be 1035 sent using. 1037 outgoingMessage: The outgoing message to send to (D)TLS for 1038 encapsulation. 1040 outgoingMessageLength: The length of the outgoing message. 1042 4.5. Cached Information and References 1044 When performing SNMP processing, there are two levels of state 1045 information that may need to be retained: the immediate state linking 1046 a request-response pair, and potentially longer-term state relating 1047 to transport and security. "Transport Subsystem for the Simple 1048 Network Management Protocol" [I-D.ietf-isms-tmsm] defines general 1049 requirements for caches and references. 1051 4.5.1. TLS Transport Model Cached Information 1053 The TLSTM has no specific responsibilities regarding the cached 1054 information beyond those discussed in "Transport Subsystem for the 1055 Simple Network Management Protocol" [I-D.ietf-isms-tmsm] 1057 5. Elements of Procedure 1059 Abstract service interfaces have been defined by RFC 3411 to describe 1060 the conceptual data flows between the various subsystems within an 1061 SNMP entity. The TLSTM uses some of these conceptual data flows when 1062 communicating between subsystems. These RFC 3411-defined data flows 1063 are referred to here as public interfaces. 1065 To simplify the elements of procedure, the release of state 1066 information is not always explicitly specified. As a general rule, 1067 if state information is available when a message gets discarded, the 1068 message-state information should also be released. If state 1069 information is available when a session is closed, the session state 1070 information should also be released. Sensitive information, like 1071 cryptographic keys, should be overwritten with zero value or random 1072 value data prior to being released. 1074 An error indication may return an OID and value for an incremented 1075 counter if the information is available at the point where the error 1076 is detected. 1078 5.1. Procedures for an Incoming Message 1080 This section describes the procedures followed by the (D)TLS 1081 Transport Model when it receives a (D)TLS protected packet. The 1082 steps are broken into two different sections. The first section 1083 describes the needed steps for de-multiplexing multiple DTLS sessions 1084 (which is needed for DTLS over UDP) and the second section describes 1085 the steps which are specific to transport processing once the (D)TLS 1086 processing has been completed. 1088 5.1.1. DTLS Processing for Incoming Messages 1090 DTLS is significantly different in terms of session handling than 1091 SSH, TLS or other TCP-based session streams. The DTLS protocol, 1092 which is datagram-based, does not have a session identifier when run 1093 over UDP that allows implementations to determine through which 1094 session a packet is arriving. DTLS over SCTP and TLS over TCP 1095 streams have built in session demultiplexing and these steps are not 1096 necessary, although it is still critical that implementations be able 1097 to derive a tlsSessionID from any demultiplexing regardless of how it 1098 is done. 1100 For DTLS over UDP a process for de-multiplexing sessions when used 1101 over UDP must be incorporated into the procedures for an incoming 1102 message. The steps in this section describe how this can be 1103 accomplished, although any implementation dependent method for doing 1104 so should be suitable as long as the results are consistently 1105 deterministic. The important results from the steps in this section 1106 are the transportDomain, the transportAddress, the wholeMessage, the 1107 wholeMessageLength, and a unique implementation-dependent session 1108 identifier. 1110 This procedure assumes that upon session establishment, an entry in a 1111 local transport mapping table is created in the Transport Model's 1112 LCD. This transport mapping table entry should be able to map a 1113 unique combination of the remote address, remote port number, local 1114 address and local port number to a implementation-dependent 1115 tlsSessionID. 1117 1) The TLS Transport Model examines the raw UDP message, in an 1118 implementation-dependent manner. If the message is not a DTLS 1119 message then it should be discarded. If the message is not a 1120 (D)TLS Application Data message then the message should be 1121 processed by the underlying DTLS framework as it is (for example) 1122 a session initialization or session modification message and no 1123 further steps below should be taken by the DTLS Transport. 1125 2) The TLS Transport Model queries the LCD using the transport 1126 parameters to determine if a session already exists and its 1127 tlsSessionID. As noted previously, the source and destination 1128 addresses and ports of the message should uniquely assign the 1129 message to a specific session identifier. However, another 1130 implementation-dependent method may be used if so desired. 1132 3) If a matching entry in the LCD does not exist then the message is 1133 discarded. Increment the tlstmSessionNoAvailableSessions counter 1134 and stop processing the message. 1136 Note that an entry would already exist if the client and server's 1137 session establishment procedures had been successfully completed 1138 (as described both above and in Section 5.3) even if no message 1139 had yet been sent through the newly established session. An 1140 entry may not exist, however, if a "rogue" message was routed to 1141 the SNMP entity by mistake. An entry might also be missing 1142 because of a "broken" session (see operational considerations). 1144 4) Retrieve the tlsSessionID from the LCD. 1146 5) The tlsWholeMsg, and the tlsSessionID are passed to DTLS for 1147 integrity checking and decryption using the tlsRead() ASI. 1149 6) If the message fails integrity checks or other (D)TLS security 1150 processing then the tlstmDTLSProtectionErrors counter is 1151 incremented, the message is discarded and processing of the 1152 message is stopped. 1154 7) The output of the tlsRead results in an incomingMessage and an 1155 incomingMessageLength. These results and the tlsSessionID are 1156 used below in the Section 5.1.2 to complete the processing of the 1157 incoming message. 1159 5.1.2. Transport Processing for Incoming Messages 1161 The procedures in this section describe how the TLS Transport Model 1162 should process messages that have already been properly extracted 1163 from the (D)TLS stream, such as described in Section 5.1.1. 1165 1) Create a tmStateReference cache for the subsequent reference and 1166 assign the following values within it: 1168 tmTransportDomain = snmpTLSDomain, snmpDTLSUDPDomain or 1169 snmpDTLSSCTPDomain as appropriate. 1171 tmTransportAddress = The address the message originated from, 1172 determined in an implementation dependent way. 1174 tmSecurityLevel = The derived tmSecurityLevel for the session, 1175 as discussed in Section 3.1.2 and Section 5.3. 1177 tmSecurityName = The derived tmSecurityName for the session as 1178 discussed in and Section 5.3. This value MUST be constant 1179 during the lifetime of the (D)TLS session. 1181 tmSessionID = The tlsSessionID, which MUST be A unique session 1182 identifier for this (D)TLS session. The contents and format 1183 of this identifier are implementation dependent as long as it 1184 is unique to the session. A session identifier MUST NOT be 1185 reused until all references to it are no longer in use. The 1186 tmSessionID is equal to the tlsSessionID discussed in 1187 Section 5.1.1. tmSessionID refers to the session identifier 1188 when stored in the tmStateReference and tlsSessionID refers to 1189 the session identifier when stored in the LCD. They MUST 1190 always be equal when processing a given session's traffic. 1192 2) The wholeMessage and the wholeMessageLength are assigned values 1193 from the incomingMessage and incomingMessageLength values from 1194 the (D)TLS processing. 1196 3) The TLS Transport Model passes the transportDomain, 1197 transportAddress, wholeMessage, and wholeMessageLength to the 1198 dispatcher using the receiveMessage ASI: 1200 statusInformation = 1201 receiveMessage( 1202 IN transportDomain -- snmpTLSDomain, snmpDTLSUDPDomain, 1203 -- or snmpDTLSSCTPDomain 1204 IN transportAddress -- address for the received message 1205 IN wholeMessage -- the whole SNMP message from (D)TLS 1206 IN wholeMessageLength -- the length of the SNMP message 1207 IN tmStateReference -- (NEW) transport info 1208 ) 1210 5.2. Procedures for an Outgoing Message 1212 The dispatcher sends a message to the TLS Transport Model using the 1213 following ASI: 1215 statusInformation = 1216 sendMessage( 1217 IN destTransportDomain -- transport domain to be used 1218 IN destTransportAddress -- transport address to be used 1219 IN outgoingMessage -- the message to send 1220 IN outgoingMessageLength -- its length 1221 IN tmStateReference -- (NEW) transport info 1222 ) 1224 This section describes the procedure followed by the TLS Transport 1225 Model whenever it is requested through this ASI to send a message. 1227 1) Extract tmSessionID, tmTransportAddress, tmSecurityName, 1228 tmRequestedSecurityLevel. and tmSameSecurity from the 1229 tmStateReference. Note: The tmSessionID value may be undefined 1230 if session exists yet. 1232 2) If tmSameSecurity is true and either tmSessionID is undefined or 1233 refers to a session that is no longer open then increment the 1234 tlstmSessionNoAvailableSessions counter, discard the message and 1235 return the error indication in the statusInformation. Processing 1236 of this message stops. 1238 3) If tmSameSecurity is false and tmSessionID refers to a session 1239 that is no longer available then an implementation SHOULD open a 1240 new session using the openSession() ASI as described below in 1241 step 4b. An implementation MAY choose to return an error to the 1242 calling module. 1244 4) If tmSessionID is undefined, then use tmTransportAddress, 1245 tmSecurityName and tmRequestedSecurityLevel to see if there is a 1246 corresponding entry in the LCD suitable to send the message over. 1248 4a) If there is a corresponding LCD entry, then this session 1249 will be used to send the message. 1251 4b) If there is not a corresponding LCD entry, then open a 1252 session using the openSession() ASI (discussed further in 1253 Section 4.4.1). Implementations MAY wish to offer message 1254 buffering to prevent redundant openSession() calls for the 1255 same cache entry. If an error is returned from 1256 OpenSession(), then discard the message, increment the 1257 tlstmSessionOpenErrors, and return an error indication to 1258 the calling module. 1260 5) Using either the session indicated by the tmSessionID if there 1261 was one or the session resulting in the previous step, pass the 1262 outgoingMessage to (D)TLS for encapsulation and transmission. 1264 5.3. Establishing a Session 1266 The TLS Transport Model provides the following primitive to establish 1267 a new (D)TLS session (previously discussed in Section 4.4.1): 1269 statusInformation = -- errorIndication or success 1270 openSession( 1271 IN destTransportDomain -- transport domain to be used 1272 IN destTransportAddress -- transport address to be used 1273 IN securityName -- on behalf of this principal 1274 IN securityLevel -- Level of Security requested 1275 OUT tlsSessionID -- Session identifier for (D)TLS 1276 ) 1278 The following sections describe the procedures followed by a TLS 1279 Transport Model when establishing a session as a Command Generator, a 1280 Notification Originator or as part of a Proxy Forwarder. 1282 The following describes the procedure to follow to establish a 1283 session between SNMP engines to exchange SNMP messages. This process 1284 is followed by any SNMP engine establishing a session for subsequent 1285 use. 1287 This MAY be done automatically for SNMP messages which are not 1288 Response or Report messages. 1290 (D)TLS provides no explicit manner for transmitting an identity the 1291 client wishes to connect to during or prior to key exchange to 1292 facilitate certificate selection at the server (e.g. at a 1293 Notification Receiver). I.E., there is no available mechanism for 1294 sending notifications to a specific principal at a given TCP, UDP or 1295 SCTP port. Therefore, implementations MAY support responding with 1296 multiple identities using separate TCP, UDP or SCTP port numbers to 1297 indicate the desired principal or some other implementation-dependent 1298 solution. 1300 1) The client selects the appropriate certificate and cipher_suites 1301 for the key agreement based on the tmSecurityName and the 1302 tmRequestedSecurityLevel for the session. For sessions being 1303 established as a result of a SNMP-TARGET-MIB based operation, the 1304 certificate will potentially have been identified via the 1305 tlstmParamsTable mapping and the cipher_suites will have to be 1306 taken from system-wide or implementation-specific configuration. 1308 Otherwise, the certificate and appropriate cipher_suites will 1309 need to be passed to the openSession() ASI as supplemental 1310 information or configured through an implementation-dependent 1311 mechanism. It is also implementation-dependent and possibly 1312 policy-dependent how tmRequestedSecurityLevel will be used to 1313 influence the security capabilities provided by the (D)TLS 1314 session. However this is done, the security capabilities 1315 provided by (D)TLS MUST be at least as high as the level of 1316 security indicated by the tmRequestedSecurityLevel parameter. 1317 The actual security level of the session should be reported in 1318 the tmStateReference cache as tmSecurityLevel. For (D)TLS to 1319 provide strong authentication, each principal acting as a Command 1320 Generator SHOULD have its own certificate. 1322 2) Using the destTransportDomain and destTransportAddress values, 1323 the client will initiate the (D)TLS handshake protocol to 1324 establish session keys for message integrity and encryption. 1326 If the attempt to establish a session is unsuccessful, then 1327 tlstmSessionOpenErrors is incremented, an error indication is 1328 returned, and session establishment processing stops. 1330 3) Once the secure session is established and both sides have been 1331 authenticated, certificate validation and identity expectations 1332 are performed. 1334 a) The (D)TLS server side of the connection identifies the 1335 authenticated identity from the (D)TLS client's principal 1336 certificate using the tlstmCertificateToSNTable mapping table 1337 and records this in the tmStateReference cache as 1338 tmSecurityName. The details of the lookup process are fully 1339 described in the DESCRIPTION clause of the 1340 tlstmCertificateToSNTable MIB object. If this verification 1341 fails in any way (for example because of failures in 1342 cryptographic verification or the lack of an appropriate row 1343 in the tlstmCertificateToSNTable) then the session 1344 establishment MUST fail, the 1345 tlstmSessionInvalidClientCertificates object is incremented 1346 and processing is stopped. 1348 b) The (D)TLS client side of the connection SHOULD verify that 1349 authenticated identity of the (D)TLS server's certificate is 1350 the expected identity and MUST do so if the client 1351 application is a Notification Generator. If strong 1352 authentication is desired then the (D)TLS server certificate 1353 MUST always be verified and checked against the expected 1354 identity. Methods for doing this are described in 1355 [I-D.saintandre-tls-server-id-check]. (D)TLS provides 1356 assurance that the authenticated identity has been signed by 1357 a trusted configured certificate authority. If verification 1358 of the server's certificate fails in any way (for example 1359 because of failures in cryptographic verification or the 1360 presented identity was not the expected identity) then the 1361 session establishment MUST fail, the 1362 tlstmSessionInvalidServerCertificates object is incremented 1363 and processing is stopped. 1365 4) The (D)TLS-specific session identifier is passed to the TLS 1366 Transport Model and associated with the tmStateReference cache 1367 entry to indicate that the session has been established 1368 successfully and to point to a specific (D)TLS session for future 1369 use. 1371 5.4. Closing a Session 1373 The TLS Transport Model provides the following primitive to close a 1374 session: 1376 statusInformation = 1377 closeSession( 1378 IN tmStateReference -- transport info 1379 ) 1381 The following describes the procedure to follow to close a session 1382 between a client and server. This process is followed by any SNMP 1383 engine closing the corresponding SNMP session. 1385 1) Look up the session in the cache and the LCD using the 1386 tmStateReference. 1388 2) If there is no session open associated with the tmStateReference, 1389 then closeSession processing is completed. 1391 3) Delete the entry from the cache and any other implementation- 1392 dependent information in the LCD. 1394 4) Have (D)TLS close the specified session. This SHOULD include 1395 sending a close_notify TLS Alert to inform the other side that 1396 session cleanup may be performed. 1398 6. MIB Module Overview 1400 This MIB module provides management of the TLS Transport Model. It 1401 defines needed textual conventions, statistical counters and 1402 configuration infrastructure necessary for session establishment. 1403 Example usage of the configuration tables can be found in Appendix A. 1405 6.1. Structure of the MIB Module 1407 Objects in this MIB module are arranged into subtrees. Each subtree 1408 is organized as a set of related objects. The overall structure and 1409 assignment of objects to their subtrees, and the intended purpose of 1410 each subtree, is shown below. 1412 6.2. Textual Conventions 1414 Generic and Common Textual Conventions used in this module can be 1415 found summarized at http://www.ops.ietf.org/mib-common-tcs.html 1417 This module defines two new Textual Conventions: a new 1418 TransportDomain and TransportAddress format for describing (D)TLS 1419 connection addressing requirements. 1421 6.3. Statistical Counters 1423 The TLSTM-MIB defines some statical counters that can provide network 1424 managers with feedback about (D)TLS session usage and potential 1425 errors that a MIB-instrumented device may be experiencing. 1427 6.4. Configuration Tables 1429 The TLSTM-MIB defines configuration tables that a manager can use for 1430 help in configuring a MIB-instrumented device for sending and 1431 receiving SNMP messages over (D)TLS. In particular, there is a MIB 1432 table that extends the SNMP-TARGET-MIB for configuring certificates 1433 to be used and a MIB table for mapping incoming (D)TLS client 1434 certificates to securityNames. 1436 6.5. Relationship to Other MIB Modules 1438 Some management objects defined in other MIB modules are applicable 1439 to an entity implementing the TLS Transport Model. In particular, it 1440 is assumed that an entity implementing the TLSTM-MIB will implement 1441 the SNMPv2-MIB [RFC3418], the SNMP-FRAMEWORK-MIB [RFC3411], the SNMP- 1442 TARGET-MIB [RFC3413], the SNMP-NOTIFICATION-MIB [RFC3413] and the 1443 SNMP-VIEW-BASED-ACM-MIB [RFC3415]. 1445 This MIB module is for managing TLS Transport Model information. 1447 6.5.1. MIB Modules Required for IMPORTS 1449 The following MIB module imports items from SNMPV2-SMI [RFC2578], 1450 SNMPV2-TC [RFC2579], SNMP-FRAMEWORK-MIB [RFC3411], SNMP-TARGET-MIB 1451 [RFC3413] and SNMP-CONF [RFC2580]. 1453 7. MIB Module Definition 1455 TLSTM-MIB DEFINITIONS ::= BEGIN 1457 IMPORTS 1458 MODULE-IDENTITY, OBJECT-TYPE, 1459 OBJECT-IDENTITY, snmpModules, snmpDomains, 1460 Counter32, Unsigned32 1461 FROM SNMPv2-SMI 1462 TEXTUAL-CONVENTION, TimeStamp, RowStatus, StorageType 1463 FROM SNMPv2-TC 1464 MODULE-COMPLIANCE, OBJECT-GROUP 1465 FROM SNMPv2-CONF 1466 SnmpAdminString 1467 FROM SNMP-FRAMEWORK-MIB 1468 snmpTargetParamsEntry 1469 FROM SNMP-TARGET-MIB 1470 ; 1472 tlstmMIB MODULE-IDENTITY 1473 LAST-UPDATED "200807070000Z" 1474 ORGANIZATION " " 1475 CONTACT-INFO "WG-EMail: 1476 Subscribe: 1478 Chairs: 1479 Co-editors: 1480 " 1482 DESCRIPTION "The TLS Transport Model MIB 1484 Copyright (C) The IETF Trust (2008). This 1485 version of this MIB module is part of RFC XXXX; 1486 see the RFC itself for full legal notices." 1487 -- NOTE to RFC editor: replace XXXX with actual RFC number 1488 -- for this document and remove this note 1490 REVISION "200807070000Z" 1491 DESCRIPTION "The initial version, published in RFC XXXX." 1492 -- NOTE to RFC editor: replace XXXX with actual RFC number 1493 -- for this document and remove this note 1495 ::= { snmpModules xxxx } 1496 -- RFC Ed.: replace xxxx with IANA-assigned number and 1497 -- remove this note 1499 -- ************************************************ 1500 -- subtrees of the SNMP-DTLS-TM-MIB 1501 -- ************************************************ 1503 tlstmNotifications OBJECT IDENTIFIER ::= { tlstmMIB 0 } 1504 tlstmObjects OBJECT IDENTIFIER ::= { tlstmMIB 1 } 1505 tlstmConformance OBJECT IDENTIFIER ::= { tlstmMIB 2 } 1507 -- ************************************************ 1508 -- Objects 1509 -- ************************************************ 1511 snmpTLSDomain OBJECT-IDENTITY 1512 STATUS current 1513 DESCRIPTION 1514 "The SNMP over TLS transport domain. The corresponding 1515 transport address is of type SnmpTLSAddress. 1517 The securityName prefix to be associated with the 1518 snmpTLSDomain is 'tls'. This prefix may be used by 1519 security models or other components to identify what secure 1520 transport infrastructure authenticated a securityName." 1522 ::= { snmpDomains xx } 1524 -- RFC Ed.: replace xx with IANA-assigned number and 1525 -- remove this note 1527 -- RFC Ed.: replace 'tls' with the actual IANA assigned prefix string 1528 -- if 'tls' is not assigned to this document. 1530 snmpDTLSUDPDomain OBJECT-IDENTITY 1531 STATUS current 1532 DESCRIPTION 1533 "The SNMP over DTLS/UDP transport domain. The corresponding 1534 transport address is of type SnmpDTLSUDPAddress. 1536 When an SNMP entity uses the snmpDTLSUDPDomain transport 1537 model, it must be capable of accepting messages up to 1538 the maximum MTU size for an interface it supports, minus the 1539 needed IP, UDP, DTLS and other protocol overheads. 1541 The securityName prefix to be associated with the 1542 snmpDTLSUDPDomain is 'dudp'. This prefix may be used by 1543 security models or other components to identify what secure 1544 transport infrastructure authenticated a securityName." 1546 ::= { snmpDomains yy } 1548 -- RFC Ed.: replace yy with IANA-assigned number and 1549 -- remove this note 1551 -- RFC Ed.: replace 'dudp' with the actual IANA assigned prefix string 1552 -- if 'dtls' is not assigned to this document. 1554 snmpDTLSSCTPDomain OBJECT-IDENTITY 1555 STATUS current 1556 DESCRIPTION 1557 "The SNMP over DTLS/SCTP transport domain. The corresponding 1558 transport address is of type SnmpDTLSSCTPAddress. 1560 When an SNMP entity uses the snmpDTLSSCTPDomain transport 1561 model, it must be capable of accepting messages up to 1562 the maximum MTU size for an interface it supports, minus the 1563 needed IP, SCTP, DTLS and other protocol overheads. 1565 The securityName prefix to be associated with the 1566 snmpDTLSSCTPDomain is 'dsct'. This prefix may be used by 1567 security models or other components to identify what secure 1568 transport infrastructure authenticated a securityName." 1570 ::= { snmpDomains zz } 1572 -- RFC Ed.: replace zz with IANA-assigned number and 1573 -- remove this note 1575 -- RFC Ed.: replace 'dsct' with the actual IANA assigned prefix string 1576 -- if 'dtls' is not assigned to this document. 1578 SnmpTLSAddress ::= TEXTUAL-CONVENTION 1579 DISPLAY-HINT "1a" 1580 STATUS current 1581 DESCRIPTION 1582 "Represents a TCP connection address for an IPv4 address, an 1583 IPv6 address or an ASCII encoded host name and port number. 1585 The hostname must be encoded in ASCII, as specified in RFC3490 1586 (Internationalizing Domain Names in Applications) followed by 1587 a colon ':' (ASCII character 0x3A) and a decimal port number 1588 in ASCII. The name SHOULD be fully qualified whenever 1589 possible. 1591 An IPv4 address must be a dotted decimal format followed by a 1592 colon ':' (ASCII character 0x3A) and a decimal port number in 1593 ASCII. 1595 An IPv6 address must be a colon separated format, surrounded 1596 by square brackets (ASCII characters 0x5B and 0x5D), followed 1597 by a colon ':' (ASCII character 0x3A) and a decimal port 1598 number in ASCII. 1600 Values of this textual convention may not be directly usable 1601 as transport-layer addressing information, and may require 1602 run-time resolution. As such, applications that write them 1603 must be prepared for handling errors if such values are not 1604 supported, or cannot be resolved (if resolution occurs at the 1605 time of the management operation). 1607 The DESCRIPTION clause of TransportAddress objects that may 1608 have snmpTLSAddress values must fully describe how (and 1609 when) such names are to be resolved to IP addresses and vice 1610 versa. 1612 This textual convention SHOULD NOT be used directly in object 1613 definitions since it restricts addresses to a specific 1614 format. However, if it is used, it MAY be used either on its 1615 own or in conjunction with TransportAddressType or 1616 TransportDomain as a pair. 1618 When this textual convention is used as a syntax of an index 1619 object, there may be issues with the limit of 128 1620 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1621 that all MIB documents using this textual convention make 1622 explicit any limitations on index component lengths that 1623 management software must observe. This may be done either by 1624 including SIZE constraints on the index components or by 1625 specifying applicable constraints in the conceptual row 1626 DESCRIPTION clause or in the surrounding documentation." 1627 SYNTAX OCTET STRING (SIZE (1..255)) 1629 SnmpDTLSUDPAddress ::= TEXTUAL-CONVENTION 1630 DISPLAY-HINT "1a" 1631 STATUS current 1632 DESCRIPTION 1633 "Represents a UDP connection address for an IPv4 address, an 1634 IPv6 address or an ASCII encoded host name and port number. 1636 The hostname must be encoded in ASCII, as specified in RFC3490 1637 (Internationalizing Domain Names in Applications) followed by 1638 a colon ':' (ASCII character 0x3A) and a decimal port number 1639 in ASCII. The name SHOULD be fully qualified whenever 1640 possible. 1642 An IPv4 address must be a dotted decimal format followed by a 1643 colon ':' (ASCII character 0x3A) and a decimal port number in 1644 ASCII. 1646 An IPv6 address must be a colon separated format, surrounded 1647 by square brackets (ASCII characters 0x5B and 0x5D), followed 1648 by a colon ':' (ASCII character 0x3A) and a decimal port 1649 number in ASCII. 1651 Values of this textual convention may not be directly usable 1652 as transport-layer addressing information, and may require 1653 run-time resolution. As such, applications that write them 1654 must be prepared for handling errors if such values are not 1655 supported, or cannot be resolved (if resolution occurs at the 1656 time of the management operation). 1658 The DESCRIPTION clause of TransportAddress objects that may 1659 have snmpDTLSUDPAddress values must fully describe how (and 1660 when) such names are to be resolved to IP addresses and vice 1661 versa. 1663 This textual convention SHOULD NOT be used directly in object 1664 definitions since it restricts addresses to a specific 1665 format. However, if it is used, it MAY be used either on its 1666 own or in conjunction with TransportAddressType or 1667 TransportDomain as a pair. 1669 When this textual convention is used as a syntax of an index 1670 object, there may be issues with the limit of 128 1671 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1672 that all MIB documents using this textual convention make 1673 explicit any limitations on index component lengths that 1674 management software must observe. This may be done either by 1675 including SIZE constraints on the index components or by 1676 specifying applicable constraints in the conceptual row 1677 DESCRIPTION clause or in the surrounding documentation." 1678 SYNTAX OCTET STRING (SIZE (1..255)) 1680 SnmpDTLSSCTPAddress ::= TEXTUAL-CONVENTION 1681 DISPLAY-HINT "1a" 1682 STATUS current 1683 DESCRIPTION 1684 "Represents a SCTP connection address for an IPv4 address, an 1685 IPv6 address or an ASCII encoded host name and port number. 1687 The hostname must be encoded in ASCII, as specified in RFC3490 1688 (Internationalizing Domain Names in Applications) followed by 1689 a colon ':' (ASCII character 0x3A) and a decimal port number 1690 in ASCII. The name SHOULD be fully qualified whenever 1691 possible. 1693 An IPv4 address must be a dotted decimal format followed by a 1694 colon ':' (ASCII character 0x3A) and a decimal port number in 1695 ASCII. 1697 An IPv6 address must be a colon separated format, surrounded 1698 by square brackets (ASCII characters 0x5B and 0x5D), followed 1699 by a colon ':' (ASCII character 0x3A) and a decimal port 1700 number in ASCII. 1702 Values of this textual convention may not be directly usable 1703 as transport-layer addressing information, and may require 1704 run-time resolution. As such, applications that write them 1705 must be prepared for handling errors if such values are not 1706 supported, or cannot be resolved (if resolution occurs at the 1707 time of the management operation). 1709 The DESCRIPTION clause of TransportAddress objects that may 1710 have snmpDTLSSCTPAddress values must fully describe how (and 1711 when) such names are to be resolved to IP addresses and vice 1712 versa. 1714 This textual convention SHOULD NOT be used directly in object 1715 definitions since it restricts addresses to a specific 1716 format. However, if it is used, it MAY be used either on its 1717 own or in conjunction with TransportAddressType or 1718 TransportDomain as a pair. 1720 When this textual convention is used as a syntax of an index 1721 object, there may be issues with the limit of 128 1722 sub-identifiers specified in SMIv2, STD 58. It is RECOMMENDED 1723 that all MIB documents using this textual convention make 1724 explicit any limitations on index component lengths that 1725 management software must observe. This may be done either by 1726 including SIZE constraints on the index components or by 1727 specifying applicable constraints in the conceptual row 1728 DESCRIPTION clause or in the surrounding documentation." 1729 SYNTAX OCTET STRING (SIZE (1..255)) 1731 X509IdentifierHashType ::= TEXTUAL-CONVENTION 1732 STATUS current 1733 DESCRIPTION 1734 "Identifies a hashing algorithm type that will be used for 1735 identifying an X.509 certificate. 1737 The md5(1) value SHOULD NOT be used." 1738 SYNTAX INTEGER { md5(1), sha1(2), sha256(3) } 1740 X509IdentifierHash ::= TEXTUAL-CONVENTION 1741 STATUS current 1742 DESCRIPTION 1743 "A hash value that uniquely identifies a certificate within a 1744 systems local certificate store. The length of the value 1745 stored in an object of type X509IdentifierHash is dependent on 1746 the hashing algorithm that produced the hash. 1748 MIB structures making use of this textual convention should 1749 have an accompanying object of type X509IdentifierHashType. 1750 " 1751 SYNTAX OCTET STRING 1753 -- The tlstmSession Group 1755 tlstmSession OBJECT IDENTIFIER ::= { tlstmObjects 1 } 1757 tlstmSessionOpens OBJECT-TYPE 1758 SYNTAX Counter32 1759 MAX-ACCESS read-only 1760 STATUS current 1761 DESCRIPTION 1762 "The number of times an openSession() request has been 1763 executed as an (D)TLS client, whether it succeeded or failed." 1764 ::= { tlstmSession 1 } 1766 tlstmSessionCloses OBJECT-TYPE 1767 SYNTAX Counter32 1768 MAX-ACCESS read-only 1769 STATUS current 1770 DESCRIPTION 1771 "The number of times a closeSession() request has been 1772 executed as an (D)TLS client, whether it succeeded or failed." 1773 ::= { tlstmSession 2 } 1775 tlstmSessionOpenErrors OBJECT-TYPE 1776 SYNTAX Counter32 1777 MAX-ACCESS read-only 1778 STATUS current 1779 DESCRIPTION 1780 "The number of times an openSession() request failed to open a 1781 session as a (D)TLS client, for any reason." 1782 ::= { tlstmSession 3 } 1784 tlstmSessionNoAvailableSessions OBJECT-TYPE 1785 SYNTAX Counter32 1786 MAX-ACCESS read-only 1787 STATUS current 1788 DESCRIPTION 1789 "The number of times an outgoing message was dropped because 1790 the session associated with the passed tmStateReference was no 1791 longer (or was never) available." 1792 ::= { tlstmSession 4 } 1794 tlstmSessionInvalidClientCertificates OBJECT-TYPE 1795 SYNTAX Counter32 1796 MAX-ACCESS read-only 1797 STATUS current 1798 DESCRIPTION 1799 "The number of times an incoming session was not established 1800 on an (D)TLS server because the presented client certificate was 1801 invalid. Reasons for invalidation includes, but is not 1802 limited to, cryptographic validation failures and lack of a 1803 suitable mapping row in the tlstmCertificateToSNTable." 1804 ::= { tlstmSession 5 } 1806 tlstmSessionInvalidServerCertificates OBJECT-TYPE 1807 SYNTAX Counter32 1808 MAX-ACCESS read-only 1809 STATUS current 1810 DESCRIPTION 1811 "The number of times an outgoing session was not established 1812 on an (D)TLS client because the presented server certificate was 1813 invalid. Reasons for invalidation includes, but is not 1814 limited to, cryptographic validation failures and an unexpected 1815 presented certificate identity." 1816 ::= { tlstmSession 6 } 1818 tlstmTLSProtectionErrors OBJECT-TYPE 1819 SYNTAX Counter32 1820 MAX-ACCESS read-only 1821 STATUS current 1822 DESCRIPTION 1823 "The number of times (D)TLS processing resulted in a message 1824 being discarded because it failed its integrity test, 1825 decryption processing or other (D)TLS processing." 1826 ::= { tlstmSession 7 } 1828 -- Configuration Objects 1830 tlstmConfig OBJECT IDENTIFIER ::= { tlstmObjects 2 } 1832 -- Certificate mapping 1834 tlstmCertificateMapping OBJECT IDENTIFIER ::= { tlstmConfig 1 } 1836 tlstmCertificateToSNCount OBJECT-TYPE 1837 SYNTAX Unsigned32 1838 MAX-ACCESS read-only 1839 STATUS current 1840 DESCRIPTION 1841 "A count of the number of entries in the 1842 tlstmCertificateToSNTable" 1843 ::= { tlstmCertificateMapping 1 } 1845 tlstmCertificateToSNTableLastChanged OBJECT-TYPE 1846 SYNTAX TimeStamp 1847 MAX-ACCESS read-only 1848 STATUS current 1849 DESCRIPTION 1850 "The value of sysUpTime.0 when the tlstmCertificateToSNTable 1851 was last modified through any means, or 0 if it has not been 1852 modified since the command responder was started." 1853 ::= { tlstmCertificateMapping 2 } 1855 tlstmCertificateToSNTable OBJECT-TYPE 1856 SYNTAX SEQUENCE OF TlstmCertificateToSNEntry 1857 MAX-ACCESS not-accessible 1858 STATUS current 1859 DESCRIPTION 1860 "A table listing the X.509 certificates known to the entity 1861 and the associated method for determining the SNMPv3 security 1862 name from a certificate. 1864 On an incoming (D)TLS/SNMP connection the client's presented 1865 certificate should be examined and validated based on an 1866 established trusted CA certificate or self-signed public 1867 certificate. This table does not provide a mechanism for 1868 uploading the certificates as that is expected to occur 1869 through an out-of-band transfer. 1871 Once the authenticity of the certificate has been verified, 1872 this table can be consulted to determine the appropriate 1873 securityName to identify the remote connection. This is done 1874 by comparing the issuer's fingerprint hash type and value and 1875 the certificate's fingerprint hash type and value against the 1876 tlstmCertHashType and tlstmCertHashValue values in each 1877 entry of this table. If a matching entry is found then the 1878 securityName is selected based on the tlstmCertMapType, 1879 tlstmCertHashType, tlstmCertHashValue and 1880 tlstmCertSecurityName fields and the resulting securityName 1881 is used to identify the other side of the (D)TLS connection. 1883 This table should be treated as an ordered list of mapping 1884 rules to check. The first mapping rule appropriately matching 1885 a certificate in the local certificate store with a 1886 corresponding hash type (tlstmCertHashType) and hash value 1887 (tlstmCertHashValue) will be used to perform the mapping from 1888 X.509 certificate values to a securityName. If, after a 1889 matching row is found but the mapping can not succeed for some 1890 other reason then further attempts to perform the mapping MUST 1891 NOT be taken. For example, if the entry being checked 1892 contains a tlstmCertMapType of bySubjectAltName(2) and an 1893 incoming connection uses a certificate with an issuer 1894 certificate matching the tlstmCertHashType and 1895 tlstmCertHashValue fields but the connecting certificate does 1896 not contain a subjectAltName field then the lookup operation 1897 must be treated as a failure. No further rows are examined for 1898 other potential mappings. 1900 Missing values of tlstmCertID are acceptable and 1901 implementations should treat missing entries as a failed match 1902 and should continue to the next highest numbered row. E.G., 1903 the table may legally contain only two rows with tlstmCertID 1904 values of 10 and 20. 1906 Users are encouraged to make use of certificates with 1907 subjectAltName fields that can be used as securityNames so 1908 that a single root CA certificate can allow all child 1909 certificate's subjectAltName to map directly to a securityName 1910 via a 1:1 transformation. However, this table is flexible 1911 enough to allow for situations where existing deployed 1912 certificate infrastructures do not provide adequate 1913 subjectAltName values for use as SNMPv3 securityNames. 1914 Certificates may also be mapped to securityNames using the 1915 CommonName portion of the Subject field which is also a 1916 scalable method of mapping certificate components to 1917 securityNames. Finally, direct mapping from each individual 1918 certificate fingerprint to a securityName is possible but 1919 requires one entry in the table per securityName." 1920 ::= { tlstmCertificateMapping 3 } 1922 tlstmCertificateToSNEntry OBJECT-TYPE 1923 SYNTAX TlstmCertificateToSNEntry 1924 MAX-ACCESS not-accessible 1925 STATUS current 1926 DESCRIPTION 1927 "A row in the tlstmCertificateToSNTable that specifies a 1928 mapping for an incoming (D)TLS certificate to a securityName 1929 to use for the connection." 1930 INDEX { tlstmCertID } 1931 ::= { tlstmCertificateToSNTable 1 } 1933 TlstmCertificateToSNEntry ::= SEQUENCE { 1934 tlstmCertID Unsigned32, 1935 tlstmCertHashType X509IdentifierHashType, 1936 tlstmCertHashValue X509IdentifierHash, 1937 tlstmCertMapType INTEGER, 1938 tlstmCertSecurityName SnmpAdminString, 1939 tlstmCertStorageType StorageType, 1940 tlstmCertRowStatus RowStatus 1941 } 1943 tlstmCertID OBJECT-TYPE 1944 SYNTAX Unsigned32 1945 MAX-ACCESS not-accessible 1946 STATUS current 1947 DESCRIPTION 1948 "A unique arbitrary number index for a given certificate 1949 entry." 1950 ::= { tlstmCertificateToSNEntry 1 } 1952 tlstmCertHashType OBJECT-TYPE 1953 SYNTAX X509IdentifierHashType 1954 MAX-ACCESS read-create 1955 STATUS current 1956 DESCRIPTION 1957 "The hash algorithm to use when applying a hash to a X.509 1958 certificate for purposes of referring to it from the 1959 tlstmCertHashValue column. 1961 The md5(1) value SHOULD NOT be used." 1962 DEFVAL { sha256 } 1963 ::= { tlstmCertificateToSNEntry 2 } 1965 tlstmCertHashValue OBJECT-TYPE 1966 SYNTAX X509IdentifierHash 1967 MAX-ACCESS read-create 1968 STATUS current 1969 DESCRIPTION 1970 "A cryptographic hash of a X.509 certificate. The use of this 1971 hash is dictated by the tlstmCertMapType column. 1972 " 1973 ::= { tlstmCertificateToSNEntry 3 } 1975 tlstmCertMapType OBJECT-TYPE 1976 SYNTAX INTEGER { specified(1), bySubjectAltName(2), byCN(3) } 1977 MAX-ACCESS read-create 1978 STATUS current 1979 DESCRIPTION 1980 "The mapping type used to obtain the securityName from the 1981 certificate. The possible values of use and their usage 1982 methods are defined as follows: 1984 specified(1): The securityName that should be used locally to 1985 identify the remote entity is directly specified 1986 in the tlstmCertSecurityName column from this 1987 table. The tlstmCertHashValue MUST refer to a 1988 X.509 client certificate that will be mapped 1989 directly to the securityName specified in the 1990 tlstmCertSecurityName column. 1992 bySubjectAltName(2): 1993 The securityName that should be used locally to 1994 identify the remote entity should be taken from 1995 the subjectAltName portion of the X.509 1996 certificate. The tlstmCertHashValue MUST refer 1997 to a trust anchor certificate that is 1998 responsible for issuing certificates with 1999 carefully controlled subjectAltName fields. 2001 byCN(3): The securityName that should be used locally to 2002 identify the remote entity should be taken from 2003 the CommonName portion of the Subject field from 2004 the X.509 certificate. The tlstmCertHashValue 2005 MUST refer to a trust anchor certificate that is 2006 responsible for issuing certificates with 2007 carefully controlled CommonName fields." 2008 DEFVAL { specified } 2009 ::= { tlstmCertificateToSNEntry 4 } 2011 tlstmCertSecurityName OBJECT-TYPE 2012 SYNTAX SnmpAdminString (SIZE(0..32)) 2013 MAX-ACCESS read-create 2014 STATUS current 2015 DESCRIPTION 2016 "The securityName that the session should use if the 2017 tlstmCertMapType is set to specified(1), otherwise the value 2018 in this column should be ignored. If tlstmCertMapType is set 2019 to specifed(1) and this column contains a zero-length string 2020 (which is not a legal securityName value) this row is 2021 effectively disabled and the match will not be considered 2022 successful." 2023 DEFVAL { "" } 2024 ::= { tlstmCertificateToSNEntry 5 } 2026 tlstmCertStorageType OBJECT-TYPE 2027 SYNTAX StorageType 2028 MAX-ACCESS read-create 2029 STATUS current 2030 DESCRIPTION 2031 "The storage type for this conceptual row. Conceptual rows 2032 having the value 'permanent' need not allow write-access to 2033 any columnar objects in the row." 2034 DEFVAL { nonVolatile } 2035 ::= { tlstmCertificateToSNEntry 6 } 2037 tlstmCertRowStatus OBJECT-TYPE 2038 SYNTAX RowStatus 2039 MAX-ACCESS read-create 2040 STATUS current 2041 DESCRIPTION 2042 "The status of this conceptual row. This object may be used 2043 to create or remove rows from this table. 2045 The value of this object has no effect on whether 2046 other objects in this conceptual row can be modified." 2047 ::= { tlstmCertificateToSNEntry 7 } 2049 -- Maps securityNames to certificates for use by the SNMP-TARGET-MIB 2051 tlstmParamsCount OBJECT-TYPE 2052 SYNTAX Unsigned32 2053 MAX-ACCESS read-only 2054 STATUS current 2055 DESCRIPTION 2056 "A count of the number of entries in the 2057 tlstmParamsTable" 2058 ::= { tlstmCertificateMapping 4 } 2060 tlstmParamsTableLastChanged OBJECT-TYPE 2061 SYNTAX TimeStamp 2062 MAX-ACCESS read-only 2063 STATUS current 2064 DESCRIPTION 2065 "The value of sysUpTime.0 when the tlstmParamsTable 2066 was last modified through any means, or 0 if it has not been 2067 modified since the command responder was started." 2068 ::= { tlstmCertificateMapping 5 } 2070 tlstmParamsTable OBJECT-TYPE 2071 SYNTAX SEQUENCE OF TlstmParamsEntry 2072 MAX-ACCESS not-accessible 2073 STATUS current 2074 DESCRIPTION 2075 "This table augments the SNMP-TARGET-MIB's 2076 snmpTargetParamsTable with an additional (D)TLS client-side 2077 certificate certificate identifier to use when establishing 2078 new (D)TLS connections." 2079 ::= { tlstmCertificateMapping 6 } 2081 tlstmParamsEntry OBJECT-TYPE 2082 SYNTAX TlstmParamsEntry 2083 MAX-ACCESS not-accessible 2084 STATUS current 2085 DESCRIPTION 2086 "A conceptual row containing a locally held certificate's hash 2087 type and hash value for a given snmpTargetParamsEntry. The 2088 values in this row should be ignored if the connection 2089 that needs to be established, as indicated by the 2090 SNMP-TARGET-MIB infrastructure, is not a (D)TLS based 2091 connection." 2092 AUGMENTS { snmpTargetParamsEntry } 2093 ::= { tlstmParamsTable 1 } 2095 TlstmParamsEntry ::= SEQUENCE { 2096 tlstmParamsHashType X509IdentifierHashType, 2097 tlstmParamsHashValue X509IdentifierHash, 2098 tlstmParamsStorageType StorageType, 2099 tlstmParamsRowStatus RowStatus 2100 } 2102 tlstmParamsHashType OBJECT-TYPE 2103 SYNTAX X509IdentifierHashType 2104 MAX-ACCESS read-create 2105 STATUS current 2106 DESCRIPTION 2107 "The hash algorithm type for the hash stored in the 2108 tlstmParamsHash column to identify a locally-held X.509 2109 certificate that should be used when initiating a (D)TLS 2110 connection as a (D)TLS client." 2111 DEFVAL { sha256 } 2112 ::= { tlstmParamsEntry 1 } 2114 tlstmParamsHashValue OBJECT-TYPE 2115 SYNTAX X509IdentifierHash 2116 MAX-ACCESS read-create 2117 STATUS current 2118 DESCRIPTION 2119 "A cryptographic hash of a X.509 certificate. This object 2120 should store the hash of a locally held X.509 certificate that 2121 should be used when initiating a (D)TLS connection as a (D)TLS 2122 client." 2123 ::= { tlstmParamsEntry 2 } 2125 tlstmParamsStorageType OBJECT-TYPE 2126 SYNTAX StorageType 2127 MAX-ACCESS read-create 2128 STATUS current 2129 DESCRIPTION 2130 "The storage type for this conceptual row. Conceptual rows 2131 having the value 'permanent' need not allow write-access to 2132 any columnar objects in the row." 2133 DEFVAL { nonVolatile } 2134 ::= { tlstmParamsEntry 3 } 2136 tlstmParamsRowStatus OBJECT-TYPE 2137 SYNTAX RowStatus 2138 MAX-ACCESS read-create 2139 STATUS current 2140 DESCRIPTION 2141 "The status of this conceptual row. This object may be used 2142 to create or remove rows from this table. 2144 The value of this object has no effect on whether 2145 other objects in this conceptual row can be modified." 2146 ::= { tlstmParamsEntry 4 } 2148 -- ************************************************ 2149 -- tlstmMIB - Conformance Information 2150 -- ************************************************ 2152 tlstmCompliances OBJECT IDENTIFIER ::= { tlstmConformance 1 } 2154 tlstmGroups OBJECT IDENTIFIER ::= { tlstmConformance 2 } 2156 -- ************************************************ 2157 -- Compliance statements 2158 -- ************************************************ 2159 tlstmCompliance MODULE-COMPLIANCE 2160 STATUS current 2161 DESCRIPTION 2162 "The compliance statement for SNMP engines that support the 2163 TLSTM-MIB" 2164 MODULE 2165 MANDATORY-GROUPS { tlstmStatsGroup, 2166 tlstmIncomingGroup, tlstmOutgoingGroup } 2167 ::= { tlstmCompliances 1 } 2169 -- ************************************************ 2170 -- Units of conformance 2171 -- ************************************************ 2172 tlstmStatsGroup OBJECT-GROUP 2173 OBJECTS { 2174 tlstmSessionOpens, 2175 tlstmSessionCloses, 2176 tlstmSessionOpenErrors, 2177 tlstmSessionNoAvailableSessions, 2178 tlstmSessionInvalidClientCertificates, 2179 tlstmSessionInvalidServerCertificates, 2180 tlstmTLSProtectionErrors 2181 } 2182 STATUS current 2183 DESCRIPTION 2184 "A collection of objects for maintaining 2185 statistical information of an SNMP engine which 2186 implements the SNMP TLS Transport Model." 2187 ::= { tlstmGroups 1 } 2189 tlstmIncomingGroup OBJECT-GROUP 2190 OBJECTS { 2191 tlstmCertificateToSNCount, 2192 tlstmCertificateToSNTableLastChanged, 2193 tlstmCertHashType, 2194 tlstmCertHashValue, 2195 tlstmCertMapType, 2196 tlstmCertSecurityName, 2197 tlstmCertStorageType, 2198 tlstmCertRowStatus 2199 } 2200 STATUS current 2201 DESCRIPTION 2202 "A collection of objects for maintaining 2203 incoming connection certificate mappings to 2204 securityNames of an SNMP engine which implements the 2205 SNMP TLS Transport Model." 2206 ::= { tlstmGroups 2 } 2208 tlstmOutgoingGroup OBJECT-GROUP 2209 OBJECTS { 2210 tlstmParamsCount, 2211 tlstmParamsTableLastChanged, 2212 tlstmParamsHashType, 2213 tlstmParamsHashValue, 2214 tlstmParamsStorageType, 2215 tlstmParamsRowStatus 2216 } 2217 STATUS current 2218 DESCRIPTION 2219 "A collection of objects for maintaining 2220 outgoing connection certificates to use when opening 2221 connections as a result of SNMP-TARGET-MIB settings." 2222 ::= { tlstmGroups 3 } 2224 END 2226 8. Operational Considerations 2228 This section discusses various operational aspects of the solution 2230 8.1. Sessions 2232 A session is discussed throughout this document as meaning a security 2233 association between the (D)TLS client and the (D)TLS server. State 2234 information for the sessions are maintained in each TLSTM and this 2235 information is created and destroyed as sessions are opened and 2236 closed. Because of the connectionless nature of UDP, a "broken" 2237 session, one side up one side down, could result if one side of a 2238 session is brought down abruptly (i.e., reboot, power outage, etc.). 2239 Whenever possible, implementations SHOULD provide graceful session 2240 termination through the use of disconnect messages. Implementations 2241 SHOULD also have a system in place for dealing with "broken" 2242 sessions. Implementations SHOULD support the session resumption 2243 feature of TLS. 2245 To simplify session management it is RECOMMENDED that implementations 2246 utilize two separate ports, one for Notification sessions and one for 2247 Command sessions. If this implementation recommendation is followed, 2248 (D)TLS clients will always send REQUEST messages and (D)TLS servers 2249 will always send RESPONSE messages. With this assertion, 2250 implementations may be able to simplify "broken" session handling, 2251 session resumption, and other aspects of session management such as 2252 guaranteeing that Request- Response pairs use the same session. 2254 Implementations SHOULD limit the lifetime of established sessions 2255 depending on the algorithms used for generation of the master session 2256 secret, the privacy and integrity algorithms used to protect 2257 messages, the environment of the session, the amount of data 2258 transferred, and the sensitivity of the data. 2260 8.2. Notification Receiver Credential Selection 2262 When an SNMP engine needs to establish an outgoing session for 2263 notifications, the snmpTargetParamsTable includes an entry for the 2264 snmpTargetParamsSecurityName of the target. However, the receiving 2265 SNMP engine (Server) does not know which (D)TLS certificate to offer 2266 to the Client so that the tmSecurityName identity-authentication will 2267 be successful. The best solution would be to maintain a one-to-one 2268 mapping between certificates and incoming ports for notification 2269 receivers, although other implementation dependent mechanisms may be 2270 used instead. This can be handled at the Notification Originator by 2271 configuring the snmpTargetAddrTable (snmpTargetAddrTDomain and 2272 snmpTargetAddrTAddress) and then requiring the receiving SNMP engine 2273 to monitor multiple incoming static ports based on which principals 2274 are capable of receiving notifications. Implementations MAY also 2275 choose to designate a single Notification Receiver Principal to 2276 receive all incoming TRAPS and INFORMS. 2278 8.3. contextEngineID Discovery 2280 Because most Command Responders have contextEngineIDs that are 2281 identical to the USM securityEngineID, the USM provides Command 2282 Generators with the ability to discover a default contextEngineID to 2283 use. Because the TLS Transport Model does not make use of a 2284 discoverable securityEngineID like the USM does, it may be difficult 2285 for Command Generators to discover a suitable default 2286 contextEngineID. Implementations should consider offering another 2287 engineID discovery mechanism to continue providing Command Generators 2288 with a contextEngineID discovery mechanism. A recommended discovery 2289 solution is documented in [RFC5343]. 2291 9. Security Considerations 2293 This document describes a transport model that permits SNMP to 2294 utilize (D)TLS security services. The security threats and how the 2295 (D)TLS transport model mitigates these threats are covered in detail 2296 throughout this document. Security considerations for DTLS are 2297 covered in [RFC4347] and security considerations for TLS are 2298 described in Section 11 and Appendices D, E, and F of TLS 1.2 2299 [RFC5246]. DTLS adds to the security considerations of TLS only 2300 because it is more vulnerable to denial of service attacks. A random 2301 cookie exchange was added to the handshake to prevent anonymous 2302 denial of service attacks. RFC 4347 recommends that the cookie 2303 exchange is utilized for all handshakes and therefore it is 2304 RECOMMENDED that implementers also support this cookie exchange. 2306 9.1. Certificates, Authentication, and Authorization 2308 Implementations are responsible for providing a security certificate 2309 configuration installation . Implementations SHOULD support 2310 certificate revocation lists and expiration of certificates or other 2311 access control mechanisms. 2313 (D)TLS provides for both authentication of the identity of the (D)TLS 2314 server and authentication of the identity of the (D)TLS client. 2315 Access to MIB objects for the authenticated principal MUST be 2316 enforced by an access control subsystem (e.g. the VACM). 2318 Authentication of the Command Generator principal's identity is 2319 important for use with the SNMP access control subsystem to ensure 2320 that only authorized principals have access to potentially sensitive 2321 data. The authenticated identity of the Command Generator 2322 principal's certificate is mapped to an SNMP model-independent 2323 securityName for use with SNMP access control. 2325 Furthermore, the (D)TLS handshake only provides assurance that the 2326 certificate of the authenticated identity has been signed by an 2327 configured accepted Certificate Authority. (D)TLS has no way to 2328 further authorize or reject access based on the authenticated 2329 identity. An Access Control Model (such as the VACM) provides access 2330 control and authorization of a Command Generator's requests to a 2331 Command Responder and a Notification Responder's authorization to 2332 receive Notifications from a Notification Originator. However to 2333 avoid man-in-the-middle attacks both ends of the (D)TLS based 2334 connection MUST check the certificate presented by the other side 2335 against what was expected. For example, Command Generators must 2336 check that the Command Responder presented and authenticated itself 2337 with a X.509 certificate that was expected. Not doing so would allow 2338 an impostor, at a minimum, to present false data, receive sensitive 2339 information and/or provide a false-positive belief that configuration 2340 was actually received and acted upon. Authenticating and verifying 2341 the identity of the (D)TLS server and the (D)TLS client for all 2342 operations ensures the authenticity of the SNMP engine that provides 2343 MIB data. 2345 The instructions found in the DESCRIPTION clause of the 2346 tlstmCertificateToSNTable object must be followed exactly. 2347 Specifically, it is important that if a row matching a certificate or 2348 a certificate's issuer is found but the translation to a securityName 2349 using the row fails that the lookup process stops and no further rows 2350 are consulted. It is also important that the rows of the table be 2351 search in order starting with the row containing the lowest numbered 2352 tlstmCertID value. 2354 9.2. Use with SNMPv1/SNMPv2c Messages 2356 The SNMPv1 and SNMPv2c message processing described in RFC3484 (BCP 2357 74) [RFC3584] always selects the SNMPv1(1) Security Model for an 2358 SNMPv1 message, or the SNMPv2c(2) Security Model for an SNMPv2c 2359 message. When running SNMPv1/SNMPv2c over a secure transport like 2360 the TLS Transport Model, the securityName and securityLevel used for 2361 access control decisions are then derived from the community string, 2362 not the authenticated identity and securityLevel provided by the TLS 2363 Transport Model. 2365 9.3. MIB Module Security 2367 The MIB objects in this document must be protected with an adequate 2368 level of at least integrity protection, especially those objects 2369 which are writable. Since knowledge of authorization rules and 2370 certificate usage mechanisms may be considered sensitive, protection 2371 from disclosure of the SNMP traffic via encryption is also highly 2372 recommended. 2374 SNMP versions prior to SNMPv3 did not include adequate security. 2375 Even if the network itself is secure (for example by using IPSec or 2376 (D)TLS) there is no control as to who on the secure network is 2377 allowed to access and GET/SET (read/change/create/delete) the objects 2378 in this MIB module. 2380 It is RECOMMENDED that implementers consider the security features as 2381 provided by the SNMPv3 framework (see section 8 of [RFC3410]), 2382 including full support for the USM (see [RFC3414]) and the TLS 2383 Transport Model cryptographic mechanisms (for authentication and 2384 privacy). 2386 10. IANA Considerations 2388 IANA is requested to assign: 2390 1. a TCP port number in the range 1..1023 in the 2391 http://www.iana.org/assignments/port-numbers registry which will 2392 be the default port for SNMP command messages over a TLS 2393 Transport Model as defined in this document, 2395 2. a TCP port number in the range 1..1023 in the 2396 http://www.iana.org/assignments/port-numbers registry which will 2397 be the default port for SNMP notification messages over a TLS 2398 Transport Model as defined in this document, 2400 3. a UDP port number in the range 1..1023 in the 2401 http://www.iana.org/assignments/port-numbers registry which will 2402 be the default port for SNMP command messages over a DTLS/UDP 2403 connection as defined in this document, 2405 4. a UDP port number in the range 1..1023 in the 2406 http://www.iana.org/assignments/port-numbers registry which will 2407 be the default port for SNMP notification messages over a DTLS/ 2408 UDP connection as defined in this document, 2410 5. a SCTP port number in the range 1..1023 in the 2411 http://www.iana.org/assignments/port-numbers registry which will 2412 be the default port for SNMP command messages over a DTLS/SCTP 2413 connection as defined in this document, 2415 6. a SCTP port number in the range 1..1023 in the 2416 http://www.iana.org/assignments/port-numbers registry which will 2417 be the default port for SNMP notification messages over a DTLS/ 2418 SCTP connection as defined in this document, 2420 7. an SMI number under snmpDomains for the snmpTLSDomain object 2421 identifier, 2423 8. an SMI number under snmpDomains for the snmpDTLSUDPDomain object 2424 identifier, 2426 9. an SMI number under snmpDomains for the snmpDTLSSCTPDomain 2427 object identifier, 2429 10. a SMI number under snmpModules, for the MIB module in this 2430 document, 2432 11. "tls" as the corresponding prefix for the snmpTLSDomain in the 2433 SNMP Transport Model registry, 2435 12. "dudp" as the corresponding prefix for the snmpDTLSUDPDomain in 2436 the SNMP Transport Model registry, 2438 13. "dsct" as the corresponding prefix for the snmpDTLSSCTPDomain in 2439 the SNMP Transport Model registry; 2441 11. Acknowledgements 2443 This document closely follows and copies the Secure Shell Transport 2444 Model for SNMP defined by David Harrington and Joseph Salowey in 2445 [I-D.ietf-isms-secshell]. 2447 This document was reviewed by the following people who helped provide 2448 useful comments: David Harrington, Alan Luchuk, Ray Purvis. 2450 This work was supported in part by the United States Department of 2451 Defense. Large portions of this document are based on work by 2452 General Dynamics C4 Systems and the following individuals: Brian 2453 Baril, Kim Bryant, Dana Deluca, Dan Hanson, Tim Huemiller, John 2454 Holzhauer, Colin Hoogeboom, Dave Kornbau, Chris Knaian, Dan Knaul, 2455 Charles Limoges, Steve Moccaldi, Gerardo Orlando, and Brandon Yip. 2457 12. References 2459 12.1. Normative References 2461 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2462 Requirement Levels", BCP 14, RFC 2119, March 1997. 2464 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2465 Schoenwaelder, Ed., "Structure of Management Information 2466 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2468 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2469 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 2470 STD 58, RFC 2579, April 1999. 2472 [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 2473 "Conformance Statements for SMIv2", STD 58, RFC 2580, 2474 April 1999. 2476 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 2477 Architecture for Describing Simple Network Management 2478 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 2479 December 2002. 2481 [RFC3413] Levi, D., Meyer, P., and B. Stewart, "Simple Network 2482 Management Protocol (SNMP) Applications", STD 62, 2483 RFC 3413, December 2002. 2485 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 2486 (USM) for version 3 of the Simple Network Management 2487 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 2489 [RFC3415] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 2490 Access Control Model (VACM) for the Simple Network 2491 Management Protocol (SNMP)", STD 62, RFC 3415, 2492 December 2002. 2494 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 2495 Simple Network Management Protocol (SNMP)", STD 62, 2496 RFC 3418, December 2002. 2498 [RFC3584] Frye, R., Levi, D., Routhier, S., and B. Wijnen, 2499 "Coexistence between Version 1, Version 2, and Version 3 2500 of the Internet-standard Network Management Framework", 2501 BCP 74, RFC 3584, August 2003. 2503 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2504 Security", RFC 4347, April 2006. 2506 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2507 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2509 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2510 Housley, R., and W. Polk, "Internet X.509 Public Key 2511 Infrastructure Certificate and Certificate Revocation List 2512 (CRL) Profile", RFC 5280, May 2008. 2514 [I-D.ietf-isms-transport-security-model] 2515 Harington, D., "Transport Security Model for SNMP". 2517 [I-D.ietf-isms-tmsm] 2518 Harington, D. and J. Schoenwaelder, "Transport Subsystem 2519 for the Simple Network Management Protocol (SNMP)". 2521 [X509] Rivest, R., Shamir, A., and L. M. Adleman, "A Method for 2522 Obtaining Digital Signatures and Public-Key 2523 Cryptosystems". 2525 12.2. Informative References 2527 [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management 2528 Protocol", RFC 2522, March 1999. 2530 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 2531 "Introduction and Applicability Statements for Internet- 2532 Standard Management Framework", RFC 3410, December 2002. 2534 [RFC4302] Kent, S., "IP Authentication Header", RFC 4302, 2535 December 2005. 2537 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 2538 RFC 4303, December 2005. 2540 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 2541 RFC 4306, December 2005. 2543 [I-D.ietf-isms-secshell] 2544 Harington, D. and J. Salowey, "Secure Shell Transport 2545 Model for SNMP". 2547 [RFC5343] Schoenwaelder, J., "Simple Network Management Protocol 2548 (SNMP) Context EngineID Discovery". 2550 [I-D.saintandre-tls-server-id-check] 2551 Saint-Andre, P., Zeilenga, K., Hodges, J., and B. Morgan, 2552 "Best Practices for Checking of Server Identities in the 2553 Context of Transport Layer Security (TLS)". 2555 [AES] National Institute of Standards, "Specification for the 2556 Advanced Encryption Standard (AES)". 2558 [DES] National Institute of Standards, "American National 2559 Standard for Information Systems-Data Link Encryption". 2561 [DSS] National Institute of Standards, "Digital Signature 2562 Standard". 2564 [RSA] Rivest, R., Shamir, A., and L. Adleman, "A Method for 2565 Obtaining Digital Signatures and Public-Key 2566 Cryptosystems". 2568 Appendix A. Target and Notificaton Configuration Example 2570 Configuring the SNMP-TARGET-MIB and NOTIFICATION-MIB along with 2571 access control settings for the SNMP-VIEW-BASED-ACM-MIB can be a 2572 daunting task without an example to follow. The following section 2573 describes an example of what pieces must be in place to accomplish 2574 this configuration. 2576 The isAccessAllowed() ASI requires configuration to exist in the 2577 following SNMP-VIEW-BASED-ACM-MIB tables: 2579 vacmSecurityToGroupTable 2580 vacmAccessTable 2581 vacmViewTreeFamilyTable 2583 The only table that needs to be discussed as particularly different 2584 here is the vacmSecurityToGroupTable. This table is indexed by both 2585 the SNMPv3 security model and the security name. The security model, 2586 when TLSTM is in use, should be set to the value of XXX corresponding 2587 to the TSM [I-D.ietf-isms-transport-security-model]. An example 2588 vacmSecurityToGroupTable row might be filled out as follows (using a 2589 single SNMP SET request): 2591 Note to RFC editor: replace XXX in the previous paragraph above with 2592 the actual IANA-assigned number for the TSM security model and remove 2593 this note. 2595 vacmSecurityModel = XXX (TSM) 2596 vacmSecurityName = "blueberry" 2597 vacmGroupaName = "administrators" 2598 vacmSecurityToGroupStorageType = 3 (nonVolatile) 2599 vacmSecurityToGroupStatus = 4 (createAndGo) 2601 Note to RFC editor: replace XXX in the vacmSecurityModel line above 2602 with the actual IANA-assigned number for the TSM security model and 2603 remove this note. 2605 This example will assume that the "administrators" group has been 2606 given proper permissions via rows in the vacmAccessTable and 2607 vacmViewTreeFamilyTable. 2609 Depending on whether this VACM configuration is for a Command 2610 Responder or a Command Generator the security name "blueberry" will 2611 come from a few different locations. 2613 For Notification Generator's performing authorization checks, the 2614 server's certificate must be verified against the expected 2615 certificate before proceeding to send the notification. The 2616 securityName be set by the SNMP-TARGET-MIB's 2617 snmpTargetParamsSecurityName column or other configuration mechanism 2618 and the certificate to use would be taken from the appropriate entry 2619 in the tlstmParamsTable. The tlstmParamsTable augments the SNMP- 2620 TARGET-MIB's snmpTargetParamsTable with client-side certificate 2621 information. 2623 For Command Responder applications, the vacmSecurityName "blueberry" 2624 value is a value that needs to come from an incoming (D)TLS session. 2625 The mapping from a recevied (D)TLS client certificate to a 2626 securityName is done with the tlstmCertificateToSNTable. The 2627 certificates must be loaded into the device so that a 2628 tlstmCertificateToSNEntry may refer to it. As an example, consider 2629 the following entry which will provide a mapping from a X.509's hash 2630 fingerprint directly to the "blueberry" securityName: 2632 tlstmCertID = 1 (chosen by ordering preference) 2633 tlstmCertHashType = sha256 2634 tlstmCertHashValue = (appropriate sha256 fingerprint) 2635 tlstmCertMapType = specified(1) 2636 tlstmCertSecurityName = "blueberry" 2637 tlstmCertStorageType = 3 (nonVolatile) 2638 tlstmCertRowStatus = 4 (createAndGo) 2640 The above is an example of how to map a particular certificate to a 2641 particular securityName. It is recommended that users make use of 2642 direct subjectAltName or CommonName mappings where possible since it 2643 will provide a more scalable approach to certificate management. 2644 This entry provides an example of using a subjectAltName mapping: 2646 tlstmCertID = 1 (chosen by ordering preference) 2647 tlstmCertHashType = sha256 2648 tlstmCertHashValue = (appropriate sha256 fingerprint) 2649 tlstmCertMapType = bySubjectAltName(2) 2650 tlstmCertStorageType = 3 (nonVolatile) 2651 tlstmCertRowStatus = 4 (createAndGo) 2653 The above entry indicates the subjectAltName field for certificates 2654 created by an Issuing certificate with a corresponding hash type and 2655 value will be trusted to always produce common names that are 2656 directly 1 to 1 mappable into SNMPv3 securityNames. This type of 2657 configuration should only be used when the certificate authorities 2658 naming conventions are carefully controlled. 2660 For the example, if the incoming (D)TLS client provided certificate 2661 contained a subjectAltName of "blueberry" and the certificate was 2662 signed by a certificate matching the tlstmCertHashType and 2663 tlstmCertHashValue values above and the CA's certificate was properly 2664 installed on the device then the CommonName of "blueberry" would be 2665 used as the securityName for the session. 2667 Author's Address 2669 Wes Hardaker 2670 Sparta, Inc. 2671 P.O. Box 382 2672 Davis, CA 95617 2673 US 2675 Phone: +1 530 792 1913 2676 Email: ietf@hardakers.net