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