idnits 2.17.1 draft-kala-dtcp-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 2 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 23, 2016) is 2709 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) -- Looks like a reference, but probably isn't: '9' on line 143 -- Looks like a reference, but probably isn't: '3' on line 560 == Missing Reference: '0-9a-f' is mentioned on line 562, but not defined -- Looks like a reference, but probably isn't: '4' on line 562 == Missing Reference: 'Criteria' is mentioned on line 1108, but not defined == Missing Reference: 'Stats' is mentioned on line 1136, but not defined -- Looks like a reference, but probably isn't: '7' on line 1679 -- Looks like a reference, but probably isn't: '8' on line 1709 ** Downref: Normative reference to an Informational RFC: RFC 1945 ** Downref: Normative reference to an Informational RFC: RFC 2104 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IP Performance Metrics Group Sumit. Kala 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track David. Cavuto 5 Expires: May 27, 2017 ATT 6 November 23, 2016 8 DTCP: Dynamic Tasking Control Protocol 9 draft-kala-dtcp-00 11 Abstract 13 Dynamic Tasking Control Protocol is a message-based interface by 14 which an authorized client may connect to a server -- usually a 15 network element (NE) or security policy enforcement point (PEP) -- 16 and issue dynamic requests for data. These tasking requests contain, 17 among other parameters, packet matching criteria that may apply to 18 certain packets flowing through that network element. The primary 19 intent of the tasking request is to instruct that network element to 20 send copies of packets matching those criteria to a destination 21 (usually via tunneling) for further inspection or other action. The 22 protocol contains a security architecture to address client or server 23 spoofing as well as replay prevention. The protocol assumes that 24 multiple clients may simultaneously control a single server. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on May 27, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Operational Modes . . . . . . . . . . . . . . . . . . . . 4 62 1.2. Performance Considerations . . . . . . . . . . . . . . . 5 63 1.3. Conventions used in this document . . . . . . . . . . . . 5 64 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 2.3. Control Source . . . . . . . . . . . . . . . . . . . . . 6 68 2.4. Content Destination . . . . . . . . . . . . . . . . . . . 6 69 2.5. Criteria . . . . . . . . . . . . . . . . . . . . . . . . 6 70 3. Overview of Operation . . . . . . . . . . . . . . . . . . . . 6 71 3.1. Request-Response Paradigm . . . . . . . . . . . . . . . . 6 72 3.2. Asynchronous Notifications . . . . . . . . . . . . . . . 8 73 3.3. Data Delivery Mechanism . . . . . . . . . . . . . . . . . 9 74 4. Security Model . . . . . . . . . . . . . . . . . . . . . . . 9 75 4.1. No Information Exposure . . . . . . . . . . . . . . . . . 9 76 4.2. Independence of Control Sources . . . . . . . . . . . . . 10 77 4.3. Control Source to Content Destination Access Control . . 10 78 4.4. Per-Message Security Mechanisms . . . . . . . . . . . . . 10 79 4.4.1. Sequence Number . . . . . . . . . . . . . . . . . . . 10 80 4.4.1.1. Sequence Number Negative Window . . . . . . . . . 11 81 4.4.2. Hashing Message Authentication Code (HMAC) . . . . . 12 82 5. Application-Layer Message Formats . . . . . . . . . . . . . . 13 83 5.1. Request General Format . . . . . . . . . . . . . . . . . 14 84 5.2. Response General Format . . . . . . . . . . . . . . . . . 14 85 5.3. Notification General Format . . . . . . . . . . . . . . . 15 86 5.4. Add Request . . . . . . . . . . . . . . . . . . . . . . . 15 87 5.4.1. Criteria Timeouts . . . . . . . . . . . . . . . . . . 17 88 5.5. Add Response . . . . . . . . . . . . . . . . . . . . . . 17 89 5.6. Delete Request . . . . . . . . . . . . . . . . . . . . . 18 90 5.7. Delete Response . . . . . . . . . . . . . . . . . . . . . 19 91 5.8. Refresh Request . . . . . . . . . . . . . . . . . . . . . 20 92 5.9. Refresh Response . . . . . . . . . . . . . . . . . . . . 21 93 5.10. List Request . . . . . . . . . . . . . . . . . . . . . . 22 94 5.11. List Response . . . . . . . . . . . . . . . . . . . . . . 23 95 5.12. NoOp Request . . . . . . . . . . . . . . . . . . . . . . 25 96 5.13. NoOp Response . . . . . . . . . . . . . . . . . . . . . . 26 97 5.14. Restart Notification . . . . . . . . . . . . . . . . . . 26 98 5.15. Rollover Notification . . . . . . . . . . . . . . . . . . 26 99 5.16. NoOp Notification . . . . . . . . . . . . . . . . . . . . 26 100 5.17. Timeout Notification . . . . . . . . . . . . . . . . . . 27 101 5.18. Congestion Notification . . . . . . . . . . . . . . . . . 27 102 5.19. CongestionDelete Notification . . . . . . . . . . . . . . 28 103 5.20. DuplicatesDropped Notification . . . . . . . . . . . . . 28 104 6. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 29 105 6.1. Special treatment of response to List request . . . . . . 29 106 6.2. Error or Exception Conditions . . . . . . . . . . . . . . 31 107 6.3. Extensions in ABNF . . . . . . . . . . . . . . . . . . . 32 108 6.4. Current Version . . . . . . . . . . . . . . . . . . . . . 32 109 6.5. No specific port . . . . . . . . . . . . . . . . . . . . 33 110 6.6. Unimplemented Protocol Methods and Parameters . . . . . . 33 111 6.7. Version Mismatches . . . . . . . . . . . . . . . . . . . 34 112 6.7.1. DTCP Client version exceeds DTCP Server version . . . 34 113 6.7.2. DTCP Server version exceeds DTCP Client version . . . 34 114 7. Message Payload Examples . . . . . . . . . . . . . . . . . . 35 115 7.1. Successful ADD Request and Response Payload . . . . . . . 35 116 7.2. Unsuccessful DELETE Request and Response Payload . . . . 36 117 8. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 36 118 9. Security Considerations . . . . . . . . . . . . . . . . . . . 43 119 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 120 11. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 43 121 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 122 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 123 Appendix A. Prior Implementation . . . . . . . . . . . . . . . . 44 124 Appendix B. DTCP Vendor-Specific Extension . . . . . . . . . . . 46 125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 127 1. Introduction 129 The Dynamic Tasking Control Protocol (DTCP) is a mechanism used to 130 dynamically control network elements in the course of performing a 131 security or other analysis on a transient network event. 133 Network Security personnel typically have little visibility into the 134 very networks they are monitoring. Routers and switches have awkward 135 mechanisms such as port mirroring and cFlowd to enable personnel some 136 meager view into the traffic flowing through a device. 138 However, when a security incident does happen to be detected, the 139 security analysis staff struggles to gain more insight as to the 140 actual content of the incident, via inference from these tools. This 141 is a time-consuming and cumbersome task. 143 cFlowd [9] and other aggregation mechanisms provide only session- 144 level statistics about the event, and fail to provide any view into 145 the actual packet data. In contrast, wholesale backhauling of port- 146 mirrored data is often cumbersome (and expensive) to set up, since it 147 requires pre-provisioned free bandwidth on wide-area links, and often 148 additional network hardware to implement. 150 The intent of DTCP is to provide a simple mechanism by which a third- 151 party device can interact with a network element or security policy- 152 enforcement-point (PEP) that normally processes packetized network 153 data, and in that interaction cause the PEP to take some action 154 (usually copy) on a defined subset of that packet data to be 155 forwarded for further inspection and analysis. 157 packet +---+ packet 158 data ->---|NE |--->- data 159 +---+ 160 ^ | 161 | | 162 DTCP ----+ +---> copy of selected packet data 164 Figure 1 - DTCP interacting with a network element. 166 Figure 1 168 The Network Element (NE) or PEP may be a firewall or proxy server, or 169 some other non-security-specific network element, such as a router or 170 a switch. This is illustrated in Figure 1. 172 1.1. Operational Modes 174 The primary operation in DTCP is the specification of the filter 175 criteria used to select or filter packets. DTCP is designed to work 176 in an IPv4 environment, and accordingly all selection criteria are 177 chosen from IPv4 and higher-layer protocol definitions. Note that 178 current DTCP syntax is limited to L3 and L4, but could be expanded to 179 higher layers. Basic filter criteria definitions have semantic (if 180 not syntactic) similarity to well-known router access-control lists 181 (ACLs) or firewall rulesets. 183 The primary operational mode of DTCP is the "copy" mode, whereby the 184 controlled network element forwards the packet towards its intended 185 destination, and also makes a copy of that packet, which it forwards 186 towards a preconfigured collection and analysis center. In this 187 mode, the original packet flow is not interrupted. DTCP makes no 188 provisions for the potential performance impact on the network 189 element when performing this function; obviously a negligible impact 190 is most desirable. 192 DTCP also supports optional modes for purely redirecting the packet 193 data (instead of making a copy of it), as well as blocking packet 194 data. These modes, if implemented, can provide additional 195 functionality for network security personnel, who may have decided 196 that particular traffic is disallowed on the network and wishes to 197 interrupt the selected flow of traffic. 199 Of critical distinction to DTCP is the basic paradigm that DTCP does 200 NOT involve a "reprovisioning" or "reconfiguration" of the controlled 201 device. DTCP is by its very nature transient; controlled devices 202 should not attempt to maintain DTCP state in a non-volatile storage 203 system. 205 1.2. Performance Considerations 207 It is envisioned that the controlling side of DTCP will be 208 implemented by both human-interactive systems and automated systems. 209 Since controlled Network Element MUST be able to respond to automated 210 requests at a potentially high rate (due to floods or other attacks), 211 the protocol implies a high performance requirement during the 212 "criteria specification" phase of the interaction. In particular, 213 the response time of the Network Element to respond to the DTCP 214 request to monitor data is of considerable importance, as the traffic 215 intended to be monitored may be short-lived. 217 While concrete performance requirements are outside the scope of this 218 document, implementers are urged to focus performance on this part of 219 the client-server interaction. 221 1.3. Conventions used in this document 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 225 document are to be interpreted as described in RFC 2119 [RFC2119]. 227 2. Definitions 229 The following sections define terms that have special significance 230 within the DTCP context. 232 2.1. Server 234 The DTCP Server is the PEP or network element that controls the data 235 of interest. The DTCP Server will be controlled in turn via DTCP. 236 The Server is responsible for maintaining state of DTCP Client 237 Requests, and forwarding data accordingly. Usually the DTCP Server 238 will be implemented on a firewall or router (or an accessory device 239 attached to one). The Server generally Responds to Requests, and can 240 also initiate Asynchronous Notifications. One Server generally 241 services more than one Client. 243 2.2. Client 245 The DTCP Client is an arbitrary host that initiates Requests to the 246 Server via DTCP. 248 2.3. Control Source 250 A Control Source is the instantiation of one DTCP Client, with 251 respect to a given Server. Each Control Source is preconfigured and 252 pre-authorized on a given Server to be able to interact with it via 253 DTCP. Control Sources may also receive Asynchronous Notifications. 254 There may be many Control Sources configured on a given Server. A 255 Control Source MUST NOT be identified by IP address; rather, Control 256 Sources are identified by user-configured character strings. 258 2.4. Content Destination 260 A Content Destination is the recipient of the extracted data, once it 261 is forwarded by the server. Content Destinations are also 262 preconfigured on the server. A Content Destination MUST NOT be 263 identified by IP address; rather, Content Destinations are identified 264 by user-configured character strings. 266 2.5. Criteria 268 The Criteria is the list of matching conditions under which a packet 269 is selected and acted upon by the server. Criteria are specified in 270 requests from the client to the server, which maintains a list of 271 active criteria for each client. 273 3. Overview of Operation 275 This section describes the basic interaction between the DTCP 276 elements, as well as the protocol message flows. 278 3.1. Request-Response Paradigm 280 The basic model for DTCP is a request-response message exchange 281 paradigm, where the server waits for messages on a specific UDP port 282 from authorized Control Sources. When a request message arrives, the 283 server processes the request, performs the necessary internal state 284 change as per the request, and then sends a reply message. 286 Note that although DTCP is specified as a message-based protocol, it 287 is designed and specified here to operate via single UDP/IP packets, 288 for performance reasons. While it is certainly possible for DTCP to 289 be operated over TCP/IP for reliable connections, such use is 290 unexplored as yet, and any implementation-specific decisions made are 291 unspecified herein. This document is written assuming that UDP will 292 be used as the Layer-4 transport mechanism. 294 A DTCP Server MUST allocate at least ONE IP address and ONE UDP port 295 for inbound connections from clients. Each DTCP Client MUST be 296 statically configured with at least ONE IP address and ONE UDP port 297 representing the server. 299 There is no mechanism defined that ensures proper configuration 300 between DTCP Clients and servers for requests and responses. 302 In general, each request and each reply are a single UDP message, 303 contained within a single IP packet. Since IP packets may be 304 fragmented during delivery, each DTCP endpoint MUST be capable of IP 305 fragment reassembly. 307 An IP packet containing a DTCP Request message from a client to a 308 server MUST have the following attributes properly set: 310 1. Destination IP Address MUST equal an IP address of a DTCP Server; 312 2. IP Protocol MUST equal 17 (UDP); 314 3. Destination UDP Port MUST equal a UDP port being listened on by 315 the respective DTCP Server. 317 The DTCP Server MUST NOT rely on the source IP address or source UDP 318 port of inbound request packets for any identification or 319 authentication of the message. 321 An IP packet containing a DTCP Reply message from a server to a 322 client MUST have the following attributes properly set: 324 1. Source IP Address MUST equal the Destination IP Address of the IP 325 packet containing the Request; 327 2. Destination IP address MUST equal the Source IP Address of the IP 328 packet containing the Request; 330 3. IP Protocol MUST equal 17 (UDP); 332 4. Destination UDP port MUST equal the Source UDP port of the UDP 333 message containing the Request; 335 5. Source UDP port MUST equal the Destination UDP port of the UDP 336 message containing the Request. 338 There is no specific UDP port registered for DTCP; rather, each DTCP 339 Server SHOULD permit the user to configure the port or set of ports 340 on which it will listen for inbound DTCP requests. Additionally, a 341 DTCP Server MAY choose to implement address or other filters on the 342 source of inbound client requests; however, this is optional and 343 implementation specific. (Recall that clients are identified by 344 strings, NOT IP addresses.) 346 3.2. Asynchronous Notifications 348 Notifications are sent out by the DTCP Server to a set of statically 349 preconfigured DTCP Clients who wish to receive notifications of 350 asynchronous events. Such messages are sent to IP addresses that 351 have been preconfigured therein. 353 A DTCP Client MAY provide a mechanism for accepting and processing 354 Notifications. The DTCP Server MUST be preconfigured with an IP 355 address and UDP port for each DTCP Client that wishes to receive 356 Notifications. 358 There is no mechanism defined that ensures proper configuration 359 between DTCP Clients and servers for Notifications. 361 An IP packet containing a DTCP Notification message from a server to 362 a client MUST have the following attributes properly set: 364 1. Destination IP address MUST equal the configured DTCP Client IP 365 address; 367 2. IP Protocol MUST equal 17 (UDP); 369 3. Destination UDP port MUST equal the configured DTCP Client UDP 370 port. 372 A future enhancement to this document may be to provide a mechanism 373 for clients to dynamically self-register for notifications. 375 A DTCP Server SHOULD include a configuration parameter for each 376 configured Control Source to indicate the Notification Version for 377 that Control Source. If such a parameter is configured for a given 378 Control Source, all Asynchronous Notifications sent from the DTCP 379 Server to that Control Source MUST precisely match the Notification 380 Version configured for that Control Source. Additionally, if such a 381 parameter is configured for a given Control Source, the DTCP Server 382 MUST NOT send Asynchronous Notifications to that Control Source that 383 do not exist in the DTCP specification indicated for that Control 384 Source. Finally, the DTCP Server MUST ensure that Asynchronous 385 Notifications whose formats have been modified in newer versions of 386 DTCP are properly formatted to meet the older DTCP specification 387 version indicated for that Control Source. 389 Note that in general the DTCP Server SHOULD accept requests from a 390 DTCP Client using a DTCP Version other than that specified in the 391 Notification Version for that client. 393 If the DTCP Server is unable to meet these requirements, upon 394 receiving a request from a DTCP Client with a mismatching version, it 395 MUST return a a "505 DTCP Version not supported" error message *using 396 the highest version supported by the DTCP Server*, and discontinue 397 processing of that request. 399 It is recommended, however, that the DTCP Server reject such a state 400 at configuration time rather than at run time. 402 3.3. Data Delivery Mechanism 404 Since the original packet IP header is not originally addressed to 405 the intended Content Destination, each DTCP Server implementation 406 MUST provide a mechanism for delivery of redirected data packets to 407 appropriate Content Destinations. This explicitly includes IP 408 checksums and IP TTL, as well as any higher-layer headers -- which 409 SHOULD NOT be altered once captured -- but may not include MAC or 410 lower-layer checksums. 412 DTCP explicitly does not specify the mechanism of data delivery to 413 the Content Destination. Such a delivery mechanism is 414 implementation- specific, and is outside the scope of this document. 416 As an example, Servers could utilize such technologies as VLAN 417 tagging or IP tunneling to deliver entire unaltered data packets to 418 Content Destinations. 420 4. Security Model 422 Since DTCP is, by design, a security protocol, it is imperative that 423 it be resistant to malicious use. 425 4.1. No Information Exposure 427 DTCP was designed with the explicit paradigm that only information 428 intentionally available to a given Control Source is ever exposed to 429 that Control Source. For example: the existence of other Control 430 Sources, or Content Destinations to which it has no access MUST NOT 431 be exposed to a given Control Source, e.g. via notifications or error 432 messages. Also, the server MUST NOT respond to any message that 433 fails its security checks. This basic paradigm MUST be upheld in 434 DTCP Server implementations. 436 4.2. Independence of Control Sources 438 DTCP may be implemented on network elements providing service to 439 different customers. If each customer is allowed access to the DTCP 440 Server, they MUST NOT be aware that another customer is using the 441 DTCP Server. More specifically, neither customer's use (or misuse) 442 of the DTCP Server can affect the other customer's use of it. 444 Limits on service-affecting actions that may be taken by a DTCP 445 Client are outside the scope of this document. 447 4.3. Control Source to Content Destination Access Control 449 A DTCP Server SHOULD provide a mechanism by which each configured 450 Control Source is granted access to one or more Content Destinations. 452 4.4. Per-Message Security Mechanisms 454 The primary motivation behind the per-message security mechanisms is 455 to provide both message integrity as well as source authenticity. 456 Additionally, providing insulation against replay-type attacks is 457 also a motivation, though secondary. 459 DTCP currently provides no mechanism for confidentiality. If 460 confidentiality is required, it is recommended that DTCP messages be 461 sent via a secure transport. 463 Note: Authentication failures, defined as a failure of these per- 464 message security mechanisms, MUST NOT be reported to the DTCP Client. 465 They SHOULD be logged on the DTCP server, and possibly acted upon by 466 administration staff. 468 4.4.1. Sequence Number 470 Every message initiated by a DTCP Client MUST contain a sequence 471 number. The request sequence number is an unsigned 64-bit whole 472 number chosen arbitrarily by the client and maintained by the server 473 persistently for each Control Source. All requests from a given 474 Control Source MUST contain a monotonically-increasing sequence 475 number. The sequence number for each successive request may 476 increment by no more than 256. The stored last-valid sequence number 477 shall only be updated upon receipt of a valid, authentic message. 479 A reply message to a valid request MUST contain the identical 480 sequence number as the associated request. 482 Other than as specified below in "Sequence Number Negative Window", 483 repetition of the last sequence number, or an invalid (non- 484 monotonically-increasing) sequence number, in an otherwise-valid 485 message MUST result in the message being dropped and a security 486 violation being logged, except when the sequence number wraps over 487 zero due to bit-field-length constraints. 489 Rollover of the sequence number shall only be permitted when the MSB 490 of the current sequence number is all-ones; otherwise this shall be 491 considered a security violation. A rollover of the sequence number 492 shall cause both an asynchronous notification message to be sent to 493 any configured static address(es) for the respective Control Source 494 as well as a log message to be generated. 496 It is suggested that clients do whatever possible to persistently 497 store the current sequence number as there is no DTCP method by which 498 to reset the current sequence number. 500 DTCP Servers SHOULD provide some mechanism for manually resetting the 501 sequence number for a given client. 503 Additionally, DTCP Servers SHOULD implement a Negative Window feature 504 as specified in the following section. 506 4.4.1.1. Sequence Number Negative Window 508 Under high load, a multithreaded DTCP client may send multiple 509 requests (with properly incrementing sequence numbers) to the DTCP 510 Server without waiting for each reply to come back individually. 511 Because packets may be reordered through the network, they may arrive 512 at the DTCP Server out of order. 514 For example, the DTCP client may send: 516 1. Request 1 (Seq = 1) 518 2. Request 2 (Seq = 2) 520 3. Request 3 (Seq = 3) 522 But due to network reordering, the DTCP Server may receive: 524 1. Request 1 (Seq = 1) 526 2. Request 3 (Seq = 3) 527 3. Request 2 (INVALID) 529 Unfortunately, the specification of the sequence number above will 530 make Request 2 invalid, because once Request 3 is processed, the 531 stored sequence number in the DTCP Server for that Client has been 532 incremented to 3. 534 Therefore to correct this problem, the DTCP Server SHOULD include a 535 "negative" window as well as the required "positive" window for 536 sequence numbers, and keep track of received sequence numbers within 537 that negative window. However, in order to maintain the replay- 538 protection afforded by the sequence number in the first place, any 539 DTCP Server implementing a negative window MUST also implement 540 tracking of particular sequence numbers received within the union of 541 both windows, and MUST NOT respond to any requests containing a 542 sequence number already received. 544 If the received sequence number is in the negative window, the DTCP 545 Server would simply store that sequence number as seen from that 546 particular DTCP Client and process the packet. If the sequence 547 number of the packet is in the positive window, the new positive and 548 negative window would begin and end at this packet's sequence number 549 respectively with the window sizes remaining the same. So a DTCP 550 packet with sequence number within the negative window but that has 551 not been seen (or anywhere within the positive window) is valid. 553 4.4.2. Hashing Message Authentication Code (HMAC) 555 A DTCP Server MUST store a statically-provisioned secret key for each 556 configured client. This key is manually shared with each DTCP 557 Client. Each request and response message MUST contain, as the last 558 entry, a parameter called Authentication-Info, whose value is the 559 HMAC algorithm specified in [RFC2104] of the rest of the message 560 payload (including the sequence number) generated using a SHA-1 [3] 561 digest and the secret key. This digest is expressed in hexadecimal 562 notation ([0-9a-f]), using 40 UTF-8 [4] characters to express the 563 160-bit SHA-1 hash. 565 Original Message: text 566 Secret Key: K 567 HMAC: hash = SHA1HMAC(K, text) 568 New Message: text + "Authentication-Info: " + hash 570 Figure 2 - Generating the message HMAC from the 571 original message. 573 Figure 2 575 The shared secret key MUST NOT be sent in any DTCP message. 577 The precise algorithm, excerpted here from RFC-2104 for reference 578 purposes (using SHA-1 as the hashing function H and byte length B=64) 579 is as follows: 581 We define two fixed and different strings ipad and opad 582 as follows 583 (the 'i' and 'o' are mnemonics for inner and outer): 584 ipad = the byte 0x36 repeated B times 585 opad = the byte 0x5C repeated B times. 587 To compute HMAC over the data `text' we perform 588 H(K XOR opad, H(K XOR ipad, text)) 590 5. Application-Layer Message Formats 592 In general, the best source for the message formats is the Formal 593 Syntax specified below. The following prose is provided for 594 informational purposes and implementation guidelines. Where apparent 595 syntactic conflicts exist, the Formal Syntax is defined to be 596 correct. 598 DTCP messages are formatted in human-readable CRLF-delimited UTF-8 599 text format, using a mechanism similar to HTTP [RFC1945] or SIP 600 [RFC3261]. Each message begins with an initial "command" line, 601 followed by an optional series of parameter-value lines. Each token 602 in the command line as well as each option line is separated by one 603 or more white space characters. The entire message MUST end with two 604 CRLFs. 606 The final token in any line MAY have whitespace before its 607 terminating CRLF, but is not so required, and is not so reflected in 608 the ABNF. DTCP servers SHOULD ignore extra whitespace between the 609 final token and the terminating CRLF, but MUST return a Syntax Error 610 otherwise. 612 Parameter names are specified in mixed case, but MUST be matched 613 regardless of case. 615 Control characters or other unprintable characters in the parameter 616 value may be indicated by a backslash (\) followed by precisely three 617 digits indicating the UTF-8 value for the character, possibly 618 including leading zeros. The backslash notation may be used to 619 express any character, including whitespace. Backslash notation is 620 explicitly forbidden from being interpreted as either an inter-token 621 delimiter or an inter-parameter delimiter. 623 DTCP Clients and server MUST NOT rely upon the order of parameters 624 within the DTCP message, since it is not guaranteed (other than the 625 final "Authentication-Info" parameter as noted below). 627 Every DTCP message MUST contain the "Authentication-Info" parameter, 628 and it MUST be the final parameter in the message. Any parameters in 629 any DTCP message following the Authentication-Info parameter MUST be 630 disregarded. 632 If a parameter appears multiple times, the behavior is undefined and 633 not guaranteed; however, if a parameter does show up multiple times, 634 the endpoint SHOULD take the value of the first occurrence and 635 disregard any successive occurrences. 637 5.1. Request General Format 639 Each client-to-server message in DTCP begins with a single request 640 command line with the following format: 642 CRLF 644 The command line is followed by one or more parameter-value pairs, 645 comprising the message body. The message is terminated by two CRLFs. 647 A DTCP request MUST contain the Sequence Number and the Control 648 Source ID parameters. 650 5.2. Response General Format 652 Each server-to-client response message in DTCP shall begin with a 653 single response line with the following format: 655 CRLF 657 where the response-code is a three-digit numeric value, and the 658 response-text is an arbitrary-length text string intended to be 659 human-readable. The response line is followed by one or more 660 parameter-value pairs comprising the message body. The message is 661 terminated by two CRLFs. 663 Responses to successful requests MUST contain the response-code "200" 664 and the response-text "OK". 666 A DTCP response MUST contain the Sequence Number parameter. A DTCP 667 response MUST also contain the Timestamp parameter. 669 5.3. Notification General Format 671 Each server-to-client notification message in the control protocol 672 shall begin with a single response line with the following format: 674 675 CRLF 677 where the response-code is a three-digit numeric value, and the 678 response-text is an arbitrary-length text string intended to be 679 human-readable. The response line is followed by one or more 680 parameter-value pairs comprising the message body. The message is 681 terminated by two CRLFs. 683 A DTCP notification message MUST contain the Timestamp parameter. 685 5.4. Add Request 687 The Add request specifies a new filter criteria to be merged with the 688 existing tasking list for a given Control Source and Content 689 Destination (regardless of order added). Any missing parameters in 690 the request will inferred to be a wildcard or "don't care". The Add 691 request MAY be accompanied by one or more of the following required 692 filter criterion parameters: 694 1. Source IP address, range or IP + bitmask, or wildcard 696 2. Destination IP address, range, or IP + bitmask, or wildcard 698 3. IP Protocol or range, or wildcard 700 4. Source Layer-4 Port or range, or wildcard (parameter only 701 meaningful when IP protocol range includes protocols 6 or 17) 703 5. Destination Layer-4 Port or range, or wildcard (parameter only 704 meaningful when IP protocol range includes 6 or 17) 706 6. ICMP Type or range, or wildcard (parameter only meaningful when 707 IP protocol range includes protocol 1) 709 7. ICMP Code or range, or wildcard (parameter only meaningful when 710 IP protocol range includes protocol 1) 712 A wildcard in a given field implies that any value will match it 713 (i.e. "don't care"). 715 Additionally, the Add request MUST contain one or more of the 716 following parameters: 718 1. Timeout specified in seconds idle (maximum one day) 720 2. Timeout specified in seconds total (maximum one day) 722 3. Timeout specified in packets (maximum 64 bits) 724 4. Timeout specified in bytes (maximum 64 bits) 726 5. Flag: Static, which indicates that this criterion will never 727 timeout and persist until explicitly deleted. All other timeouts 728 shall be ignored if a STATIC flag is present. 730 Additionally, the Add request may contain one or more of the 731 following parameters: 733 1. Relative Priority (unsigned integer, minimum value 1) (optional, 734 defaults to 1) 736 2. Flag: Send Timeout Async (optional), which will cause the server 737 to send a Asynchronous Notification when the criterion times out 738 for any reason. 740 3. Action (optional), which specifies whether the packet stream 741 identified by the criterion will be a) copied to the Content 742 Destination and also forwarded to its original intended 743 destination ("Copy"), b) copied but not forwarded ("Redirect"), 744 or c) not copied and not forwarded ("Block"). By default, Action 745 is "Copy". 747 Finally, the Add request MUST contain the following control protocol 748 parameters: 750 1. Control Source Identifier 752 2. Content Destination Identifier 754 3. Sequence number (MUST be monotonically increasing for each 755 request from a given Control Source) 757 4. HMAC authenticator (MUST span message payload, plus secret key) 759 Although not explicitly expressed in the request, the DTCP Server 760 MUST maintain the date/time of each filter criterion successfully 761 added. This time is the local DTCP Server time, either maintained 762 independently by the server or synchronized via NTP. 764 5.4.1. Criteria Timeouts 766 Timeouts are required for each filter criterion added. These 767 timeouts may be specified in any of four formats: seconds-idle, 768 seconds-total, bytes, or packets. Any combination of these four 769 timeouts may be used in a filter criterion as long as at least one is 770 used. 772 Once a criterion is added, the timeouts will begin decrementing as 773 appropriate. Only the timeouts that are specified in the request 774 will be used for timing-out that criterion. When any active timeout 775 is decremented to zero, the DTCP Server will automatically delete the 776 filter criterion. For each Control Source, if enabled, when a 777 criterion times-out and is deleted, timeout notifications will be 778 sent to any statically-configured Notification Destination(s) 779 associated with that Control Source. 781 A criterion may be added as STATIC. Any such criterion shall persist 782 in the active state unless and until explicitly deleted or deleted 783 due to congestion, provided the DTCP Server maintains its normal 784 operational state. (See section 5.18 Congestion Notification for 785 more information on congestion and timeouts.) 787 If all timeout values are zero and the criterion is not marked 788 STATIC, the DTCP Server MUST return Error 433 (Improper Timeout 789 Specification) and the criterion must not be added. For STATIC 790 criteria, the DTCP Server MUST ignore the all timeout values. 792 If the server fails, STATIC rules may be lost. Any Control Source 793 that uses STATIC criteria SHOULD attempt to ensure that such criteria 794 are still up and active following any maintenance or failure event on 795 the server. 797 5.5. Add Response 799 The response to a successful Add request will consist of the 800 following parameters: 802 Criteria ID 804 The Criteria ID will be persistent for the duration of that request, 805 until it is removed explicitly by the client, or is removed 806 implicitly by either timeout or some failure of the DTCP Server. The 807 Criteria ID MUST uniquely identify that particular filter criterion 808 for that particular Control Source (and be agnostic to the Content 809 Destination). 811 DTCP Servers MUST ensure that generated Criteria ID are unique for 812 all currently-active requests for a given Control Source. 814 Ideally, the Criteria ID SHOULD be globally unique across Control 815 Sources, but this is not strictly required (since all requests will 816 always be from a particular Control Source). 818 DTCP Servers SHOULD provide unique Criteria IDs for new requests, 819 even if old ones have been deleted resulting in a fragmented ID 820 space. This prevents race conditions that can cause inconsistent 821 behavior e.g., a criterion specified in an Add request gets the same 822 Criterion Id as a recently deleted criterion (deleted due to 823 timeout), and before the delete notification could reach the Control 824 Source, it sends out an explicit delete request for the old 825 criterion, which when received by the DTCP Server would delete the 826 recently added criterion, which is clearly undesirable. 828 This response MUST also include the following parameters: 830 1. Timestamp 832 2. Sequence number (MUST match the sequence number for the request) 834 3. HMAC authenticator (MUST span message payload, plus secret key) 836 Responses to unsuccessful Add requests may take any of the following 837 forms: 839 o Syntax Error 841 o Improper Filter Criterion Specification 843 o Unknown Destination Identifier 845 o Invalid Timeout Specification 847 o Improper Authentication (logged, but never sent to client) 849 o Invalid Sequence Number (logged, but never sent to client) 851 o Unknown Control Source Identifier (logged, but never sent to 852 client) 854 5.6. Delete Request 856 The Delete request removes a particular filter criterion (or 857 optionally all filter criteria) for the particular Control Source. 859 The Delete request MUST take precisely one of the following 860 parameters: 862 o Criteria ID or list of ranges of Criteria IDs 864 o Content Destination Identifier 866 Additionally, the Delete request may contain one or more of the 867 following parameters: 869 o Flag: Static, which indicates that criteria added as STATIC should 870 be deleted as well. (optional) If this flag is omitted, STATIC 871 criteria MUST NOT be deleted. 873 If a single Criteria ID or list of ranges Criteria IDs is specified, 874 the respective criterion/criteria is/are removed from the list of 875 filter conditions that apply for that Control Source. 877 If a Content Destination Identifier is specified, all criteria are 878 removed from the list of filter conditions to that particular Content 879 Destination for that Control Source, except for STATIC criteria 880 --unless the STATIC flag is specified. (Note that any other criteria 881 specified by any other Control Sources MUST remain unaffected.) 883 Additionally, the Delete request MUST contain the following 884 parameters: 886 o Control Source Identifier 888 o Sequence number (MUST be monotonically increasing for each request 889 from a given Control Source) 891 o HMAC authenticator (MUST span message payload, plus secret key) 893 5.7. Delete Response 895 The response to a successful Delete will consist of the following 896 parameter: 898 o Number of Criteria Deleted 900 This parameter is an integer specifying the total number of filter 901 criteria that were actually deleted. The number will be precisely 1 902 if a single, valid Criteria ID is supplied in the Delete request. If 903 multiple valid Criteria IDs are supplied, the number of criteria 904 actually deleted will be returned. 906 If any individual Criteria ID is invalid, the entire response will 907 return an error and no action shall be taken by the server for any 908 supplied Criteria ID. If a Content Destination Identifier is 909 supplied, the number of criteria deleted shall be equal to the total 910 number of active filter criteria from the requesting Control Source 911 to that particular Content Destination. If no such criteria exist, 912 the DTCP Server will return a successful delete response (with 913 criteria deleted parameter set to zero). 915 When a range is specified, any existing criteria matching the 916 Criteria ID in that range (inclusive) will be deleted and the true 917 number of criteria deleted (including possibly zero) will be 918 returned. 920 Trying to delete a STATIC criterion without the STATIC flag in the 921 Delete request will result in that criterion NOT being deleted. Such 922 a deletion attempt will return a success (non-error) response, 923 including the actual number of criteria deleted (which may be zero). 925 This response MUST also include the following parameters: 927 o Timestamp 929 o Sequence number (MUST match the sequence number for the request) 931 o HMAC authenticator (MUST span message payload, plus secret key) 933 Responses to unsuccessful Delete requests may take any of the 934 following forms: 936 o Syntax Error 938 o Unknown Criteria ID 940 o Unknown Destination Identifier 942 o Improper Authentication (logged, but never sent to client) 944 o Invalid Sequence Number (logged, but never sent to client) 946 o Unknown Control Source Identifier (logged, but never sent to 947 client) 949 5.8. Refresh Request 951 The Refresh request updates the timeout for a particular filter 952 criterion or set of filter criteria (or optionally all filter 953 criteria) for the particular Control Source assigned to a particular 954 Content Destination. This is used to maintain active criteria that 955 are in danger of timing-out based on the original Add request. The 956 updated timeout will replace the current remaining timeout, NOT be 957 added to it. The Refresh request MUST take precisely one of the 958 following parameters: 960 o Criteria ID or list of ranges of Criteria IDs 962 o Content Destination Identifier 964 Additionally, the Refresh request MUST contain one or more of the 965 following parameters: 967 o Timeout specified in seconds total 969 o Timeout specified in seconds idle 971 o Timeout specified in packets 973 o Timeout specified in bytes 975 (Note that a Refresh request MUST NOT be used to make an existing 976 filter criterion STATIC. A criterion MUST be added explicitly as 977 STATIC in its original Add.) 979 Finally, the Refresh request MUST contain the following parameters: 981 o Control Source Identifier 983 o Sequence number (MUST be monotonically increasing for each request 984 from a given Control Source) 986 o HMAC authenticator (MUST span message payload, plus secret key) 988 5.9. Refresh Response 990 The response to a successful Refresh will consist of the following 991 parameters: 993 o Number of Criteria Refreshed 995 This parameter is an integer specifying the total number of filter 996 criteria that were actually updated. The number will be precisely 1 997 if a single, valid Criteria ID is supplied. If multiple valid 998 Criteria ID are supplied, the number of criteria updated will be 999 returned, and that will equal the number of supplied Criteria IDs. 1000 If any Criteria ID is invalid, the entire response will return an 1001 error and no action shall be taken by the server for any supplied 1002 Criteria ID. If a Content Destination Identifier is supplied, the 1003 number of criteria updated shall be equal to the total number of 1004 active filter criteria from the requesting Control Source to that 1005 particular Content Destination, including zero (which will NOT return 1006 an error). 1008 This response MUST also include the following parameters: 1010 o Timestamp 1012 o Sequence number (MUST match the sequence number for the request) 1014 o HMAC authenticator (MUST span message payload, plus secret key) 1016 Responses to unsuccessful Refresh requests may take any of the 1017 following forms: 1019 o Syntax Error 1021 o Invalid Timeout Specification 1023 o Unknown Criteria ID 1025 o Unknown Destination Identifier 1027 o Improper Authentication (logged, but never sent to client) 1029 o Invalid Sequence Number (logged, but never sent to client) 1031 o Unknown Control Source Identifier (logged, but never sent to 1032 client) 1034 5.10. List Request 1036 The List request makes no change on the DTCP Server, but returns a 1037 list of all criteria that a particular Control Source has added. The 1038 Control Source may request this list on the basis of Content 1039 Destination, Criteria ID, or overall (for that particular Control 1040 Source). The List request takes the following parameters: 1042 o Content Destination Identifier (optional) 1044 o Criteria ID or List of ranges of Criteria IDs (optional) 1046 o Flag: Statistics / Criteria / All 1047 If neither of the optional parameters is included, the server MUST 1048 reply with the full set of criteria associated with that Control 1049 Source. 1051 Additionally, the List request MUST contain the following parameters: 1053 o Control Source Identifier 1055 o Sequence number (MUST be monotonically increasing for each request 1056 from a given Control Source) 1058 o HMAC authenticator (MUST span message payload, plus secret key) 1060 5.11. List Response 1062 The response to a successful List will consist of a formatted list -- 1063 essentially a table -- of filter criteria and related parameters. 1065 Fields will be included and excluded depending on the presence and 1066 the value of Stats/Criteria/All entry in the request as noted in 1067 square brackets [] following the value listed below. Each entry in 1068 the List list shall contain the following fields as specified in the 1069 original criteria: 1071 o Control Source Identifier 1073 o Control Source IP Address 1075 o Content Destination Identifier 1077 o Criteria ID 1079 o Date/Time added 1081 o Specified Source IP address, range or IP + bitmask , or wildcard 1082 [Criteria] 1084 o Specified Destination IP address, range, or IP + bitmask, or 1085 wildcard [Criteria] 1087 o IP Protocol or range, or wildcard [Criteria] 1089 o Source Layer-4 Port or range, or wildcard (parameter only 1090 meaningful when IP protocol range includes protocols 6 or 17) 1091 [Criteria] 1093 o Destination Layer-4 Port or range, or wildcard (parameter only 1094 meaningful when IP protocol range includes 6 or 17) [Criteria] 1096 o ICMP Type or range, or wildcard (parameter only meaningful when IP 1097 protocol range includes protocol 1) [Criteria] 1099 o ICMP Code or range, or wildcard (parameter only meaningful when IP 1100 protocol range includes protocol 1) [Criteria] 1102 o Timeout specified in seconds total [Criteria] 1104 o Timeout specified in seconds idle [Criteria] 1106 o Timeout specified in packets [Criteria] 1108 o Timeout specified in bytes [Criteria] 1110 The List list shall also contain the following statistical 1111 information based on each criterion: 1113 o An ordinal counter to specify the position of this entry in the 1114 context of the list 1116 o An integer specifying the total number of entries in the list 1118 o Timeout remaining in seconds total [Stats] 1120 o Timeout remaining in seconds idle [Stats] 1122 o Timeout remaining in packets [Stats] 1124 o Timeout remaining in bytes [Stats] 1126 o An indication if the timeout is STATIC 1128 o Last 10-second average bandwidth, in bits/second [Stats] 1130 o Total number of packets that have matched this Criteria [Stats] 1132 o Total number of bytes that have matched this Criteria [Stats] 1134 o Total times this rule has been Refreshed [Stats] 1136 o Date/Time of last Refresh [Stats] 1138 This response MUST also include the following parameters: 1140 o Timestamp 1142 o Sequence number (MUST match the sequence number for the request) 1143 o HMAC authenticator (MUST span message payload, plus secret key) 1145 Responses to unsuccessful List requests may take any of the following 1146 forms: 1148 o Syntax Error 1150 o Unknown Destination Identifier 1152 o Unknown Criteria ID 1154 o Improper Authentication (logged, but never sent to client) 1156 o Invalid Sequence Number (logged, but never sent to client) 1158 o Unknown Control Source Identifier (logged, but never sent to 1159 client) 1161 Important Note: the response to the List message, in particular all 1162 entries in the generated table, SHOULD be internally consistent and 1163 atomic, regardless of the activity in progress at the time of and 1164 during the course of transmission of the message. The data SHOULD 1165 represent a snapshot of the relevant information at the quantum in 1166 time that the List message is processed. 1168 5.12. NoOp Request 1170 This request takes no action on the server whatsoever, other than 1171 returning a successful response. The sole purpose of this command is 1172 to verify the end-to-end application-layer connectivity between a 1173 Control Source and the DTCP Server. The NoOp request may contain the 1174 following parameter: 1176 o Flag: SendAsync 1178 See 5.13 NoOp Response for a description of the SendAsync flag. 1180 Additionally, the NoOp request MUST contain the following parameters: 1182 o Control Source Identifier 1184 o Sequence number (MUST be monotonically increasing for each request 1185 from a given Control Source) 1187 o HMAC authenticator (MUST span message payload, plus secret key) 1189 5.13. NoOp Response 1191 The response to a successful NoOp will consist of a successful 1192 response message indicator, and contain the following parameters: 1194 o Timestamp 1196 o Sequence number (MUST match the sequence number for the request) 1198 o HMAC authenticator (MUST span message payload, plus secret key) 1200 If the SendAsync parameter is specified in the NoOp request, the 1201 server shall cause an asynchronous notification message to be sent to 1202 any configured notification destinations for that particular Control 1203 Source. 1205 5.14. Restart Notification 1207 The Restart notification shall be sent from the server to any 1208 configured notification-recipient when the system experiences a 1209 failure such that all the filter criteria are lost. The Restart 1210 notification shall contain the following parameters: 1212 o Restart Reason, a text string indicating the reason for the 1213 restart, if known 1215 o Timestamp 1217 o HMAC authenticator (MUST span message payload, plus secret key) 1219 5.15. Rollover Notification 1221 The Rollover notification shall be sent from the server to any 1222 configured notification-recipient when the server experiences a 1223 sequence-number rollover. The Rollover notification shall contain 1224 the following parameters: 1226 o Timestamp 1228 o HMAC authenticator (MUST span message payload, plus secret key) 1230 5.16. NoOp Notification 1232 The NoOp notification shall be sent from the server to any configured 1233 notification-recipient when the DTCP Server receives a NoOp message 1234 with the SendAsync parameter present. The NoOp notification shall 1235 contain the following parameters: 1237 o Timestamp 1239 o HMAC authenticator (MUST span message payload, plus secret key) 1241 5.17. Timeout Notification 1243 The Timeout notification shall be sent from the server to the 1244 appropriate notification-recipient(s) when the server times out a 1245 filter criterion on any one of its configured timeout parameters and 1246 the criterion contains a SendTimeoutAsync parameter. 1248 The Timeout notification shall contain the following parameters: 1250 o Criteria ID, to indicate the particular criteria that has timed 1251 out 1253 o Timeout specified in seconds total [omit if unconfigured] 1255 o Timeout remaining in seconds total [omit if unconfigured] 1257 o Timeout specified in seconds idle [omit if unconfigured] 1259 o Timeout remaining in seconds idle [omit if unconfigured] 1261 o Timeout specified in packets [omit if unconfigured] 1263 o Timeout remaining in packets [omit if unconfigured] 1265 o Timeout specified in bytes [omit if unconfigured] 1267 o Timeout remaining in bytes [omit if unconfigured] 1269 o Timestamp 1271 o HMAC authenticator (MUST span message payload, plus secret key) 1273 5.18. Congestion Notification 1275 The Congestion notification shall be sent from the server to any 1276 configured notification-recipient when the total 10-second average 1277 data rate (in bits/second) summed over all active filter criteria to 1278 a configured Content Destination exceeds the configured soft limit 1279 for that destination. The Congestion notification shall contain the 1280 following parameters: 1282 o Content Destination ID, to indicate the particular destination 1283 experiencing excessive bandwidth 1285 o Current total 10-second average Bandwidth, in bits/second 1287 o Configured SoftLimit Threshold, in bits/second 1289 o Configured HardLimit Threshold, in bits/second 1291 o Timestamp 1293 o HMAC authenticator (MUST span message payload, plus secret key) 1295 Note that since multiple Control Sources may be responsible for this 1296 overload, this Notification MUST be sent to all configured Control 1297 Sources that have currently-active filter criteria to this particular 1298 Content Destination. 1300 5.19. CongestionDelete Notification 1302 The CongestionDelete notification shall be sent from the server to 1303 any configured notification-recipient when the total 10-second 1304 average data rate (in bits/second) summed over all active filter 1305 criteria to a configured Content Destination exceeds the configured 1306 hard limit for that destination, causing the DTCP Server to begin 1307 purging filter criteria. The CongestionDelete notification shall 1308 contain the following parameters: 1310 o Content Destination ID 1312 o List of Criteria ID purged 1314 o Timestamp 1316 o HMAC authenticator (MUST span message payload, plus secret key) 1318 CongestionDelete messages MUST be specifically and uniquely sent to 1319 all configured notification-recipients for the Control Sources to 1320 which they apply. To be clear: a given Control Source notification- 1321 recipient MUST only receive CongestionDelete messages containing 1322 Criteria ID created by that Control Source. 1324 5.20. DuplicatesDropped Notification 1326 The DuplicatesDropped notification shall be sent from the server to 1327 any configured notification-recipient when capacity has been exceeded 1328 in such a way as to cause packets matching criteria added by the 1329 corresponding Control Source to be dropped. This notification will 1330 be sent periodically as long as packets continue to be dropped. The 1331 DuplicatesDropped notification shall contain the following 1332 parameters: 1334 o Content Destination ID 1336 o Applicable CriteriaID pertaining to Dropped Packets 1338 o Total Number of Dropped Packets 1340 o Sum of Bytes contained in Dropped Packets 1342 o Timestamp 1344 o HMAC authenticator (MUST span message payload, plus secret key) 1346 DuplicatesDropped messages MUST be specifically and uniquely sent to 1347 all configured notification-recipients for the Control Sources to 1348 which they apply. 1350 6. Miscellaneous 1352 6.1. Special treatment of response to List request 1354 The List request inherently provides unique functionality with 1355 respect to the messaging architecture of DTCP. All other requests 1356 result in reasonably terse replies, which can be encapsulated in, at 1357 worst, a few IP packets. 1359 However, the List request will generate an arbitrary amount of reply 1360 data, since it could contain all requests that are still active, up 1361 to the limit of the device. This section specifically describes how 1362 responses to the List request are sent. 1364 a) The full reply to the List request MAY consist of multiple 1365 packets. Each packet will contain a single "Response" element; 1366 therefore, each packet will have a single Status-Line and a single 1367 trailer (Authentication-Info) terminated by 2xCRLF. A UDP packet 1368 MUST NOT contain more than ONE "Response" element. 1370 b) A "Response" element in each packet shall contain zero or more 1371 "List-Resp-Entry" elements (in "List-Resp-Parameters"). Each filter 1372 criteria is encoded into a single "List-Resp-Entry" element. The 1373 sequence number MUST be identical for all "Response" elements in a 1374 multi-packet reply. 1376 c) Each "List-Resp-Entry" element MUST contain the following two 1377 elements: "Criteria-Num" and "Criteria-Count". "Criteria-Num" MUST 1378 be valued as an enumeration starting with 1 (one) and incrementing by 1379 one for each "List-Resp-Entry" sent. "Criteria-Count" SHOULD be set 1380 to the total number of matching Criteria in the given particular LIST 1381 response (see below for potential exceptions). 1383 d) Therefore, a full reply to the List request shall consist of as 1384 many "List-Resp-Entry" elements as necessary to fully transmit the 1385 List, divided into multiple packets as described above. 1387 e) DTCP Servers SHOULD ensure that each "List-Resp-Entry" element is 1388 not divided across multiple IP packets. 1390 f) DTCP Clients can use the simple test (Criteria-Num==Criteria- 1391 Count) to determine if they've received the last packet in the 1392 series. However, in order to ensure that all packets were received 1393 (and, respectively, all List-Resp-Entry elements), the DTCP Client 1394 MUST traverse through the list of Criteria-Count to ensure it's 1395 complete from 1 to XX where XX==Criteria-Num==Criteria-Count. 1397 g) At the UDP layer, all packets in the response MUST contain 1398 identical UDP port numbers. DTCP Clients SHOULD maintain their 1399 socket open until either all expected Response messages are received, 1400 or a timeout occurs. 1402 h) If the List request matches no criteria, but does not supply 1403 invalid Criteria-IDs, the "Response" element will contain zero "List- 1404 Resp-Entry" elements. 1406 i) DTCP Servers MAY simplify their implementation by only including a 1407 single "List-Resp-Entry" element in each "Response" element (and 1408 therefore in each packet). 1410 j) DTCP Servers MAY simplify their implementation by transmitting the 1411 "Criteria-Count" element in each List-Resp-Entry element as ZERO (0) 1412 until the final element is sent, whereupon it is set to the proper 1413 value. 1415 A List response that matches 3 criteria may look as follows: 1417 =============== First UDP packet 1418 DTCP header 1419 Seq: A 1420 criteria-id: x ; this is the first List-Resp-Entry element 1421 ... 1422 criteria-num: 1 1423 criteria-count: 3 1424 criteria-id: y ; this is the second List-Resp-Entry element 1425 ... 1426 criteria-num: 2 1427 criteria-count: 3 1428 HMAC 1429 ================ 1430 =============== Second UDP packet 1431 DTCP header 1432 Seq: A 1433 criteria-id: z ; this is the third List-Resp-Entry element 1434 ... 1435 criteria-num: 3 1436 criteria-count: 3 1437 HMAC 1438 ================ 1440 If the list request matches no criteria, it will look as follows: 1442 =============== First UDP packet 1443 DTCP header 1444 Seq: B 1445 HMAC 1446 ================ 1448 6.2. Error or Exception Conditions 1450 Errors in DTCP requests are reported in response messages via any 1451 Response-Code other than "200" (OK). When such error or exception 1452 condition exists, the server SHOULD attempt to indicate the precise 1453 nature of the error or exception using the Error-Parameters element. 1454 This behavior, though helpful, is not strictly required by the 1455 protocol. 1457 For example, if a Delete request contained a specific Criteria-ID not 1458 currently active in the server, the response error message MUST begin 1459 with a 431 - Unknown Criteria ID response line. The server SHOULD 1460 also add the Criteria-ID parameter indicating the unknown Criteria 1461 ID. 1463 Again, note that authentication failures MUST NOT be reported in 1464 response messages; they MUST be silently dropped. 1466 The DTCP Server MUST attempt to provide the most specific error 1467 message to report the specific error or exception condition. When 1468 the request message meets any of the following conditions, if no such 1469 specific error message exists, the server MAY return a 400 (Bad 1470 Request) error: 1472 o Missing required fields 1474 o Parse failure 1476 o Parameters beyond range 1478 In these cases, the server SHOULD include the specific line from the 1479 request that caused the condition using the Error-Parameters element. 1481 6.3. Extensions in ABNF 1483 Extension placeholders are provided in the formal syntax for the 1484 definition of future methods, parameters, and response-codes. 1485 Vendors SHOULD NOT define implementation-specific extensions; rather, 1486 such extensions SHOULD be brought to the DTCP working group for 1487 inclusion into the protocol, to ensure interoperability. 1489 However, in order to provide faster extensions to the protocol, the 1490 "X-" extension parameter construct has been borrowed from other 1491 protocols, including SIP and SMTP. 1493 The DTCP Server or the DTCP Client MAY include an arbitrary 1494 parameter-value pair, as long as the parameter is preceded by the 1495 character string "X-", and all other parameter-value conventions are 1496 followed. 1498 The sender of such extension parameters MUST NOT rely on the 1499 recipient correctly processing those values. 1501 The recipient of such extension parameters MAY process the values as 1502 appropriate upon receipt, but MUST discard without error those 1503 extension parameters that it does not recognize. 1505 6.4. Current Version 1507 The current version string for this release of the DTCP protocol is: 1509 DTCP/0.7 1511 6.5. No specific port 1513 While it is common practice to register and/or publish a TCP or UDP 1514 port for applications that define them as a layer-4 transport, DTCP 1515 has no specific UDP ports predefined. This is intended both to allow 1516 flexibility for implementers and users, as well as to make it more 1517 difficulty to detect DTCP messages on untrusted networks. 1519 6.6. Unimplemented Protocol Methods and Parameters 1521 Some DTCP Server vendors have indicated their interest in supporting 1522 a subset of the functionality specified here, due to their position 1523 in the security space. Additionally, some constructs (arbitrary 1524 lists, in particular) add complexity to implementations that may not 1525 require that complexity. 1527 To address this need, rather than adding complexity by changing the 1528 grammar to indicate optional sections, specific error messages have 1529 been added to indicate to the client that the server cannot process 1530 the request in its current format. Depending on the request, the 1531 client might be able to reformat that request into one that the 1532 server implementation is able to process. 1534 In order to be compliant with this protocol, the following rules 1535 apply: 1537 a) If a vendor chooses not to implement one or more DTCP Methods, 1538 when responding to a request containing one of the unsupported 1539 methods, the DTCP Server MUST send a "501 Not Implemented" Response 1540 error message, and discontinue processing of that request. 1542 b) If a vendor chooses not to implement a list element, when 1543 responding to a request containing such a list, the DTCP Server MUST 1544 send a "501 Not Implemented" Response error message, and discontinue 1545 processing of that request. 1547 c) If a vendor chooses not to implement one or more specific 1548 parameters or parameter value options in a request, the DTCP Server 1549 MUST send a "501 Not Implemented" Response error message, and 1550 discontinue processing of that request. 1552 d) The DTCP Server SHOULD include the method, parameter, or value 1553 which caused the "501 Not Implemented" error to be sent, within the 1554 error response message (to be consistent with 6.4 above) 1556 e) The DTCP Server SHOULD support prior versions of DTCP. However, 1557 if the vendor chooses not to implement prior versions of the 1558 protocol, the DTCP Server MUST send a "505 DTCP Version not 1559 supported" error message, and discontinue processing of that request. 1561 The onus is on the client to determine if it can reformat the message 1562 to make it acceptable to the particular DTCP Server implementation. 1564 6.7. Version Mismatches 1566 The intent of this section is to clarify any ambiguity arising from 1567 mismatches between DTCP versions supported by the DTCP Client and the 1568 DTCP Server. In practice is has been observed that unintended 1569 consequences have arisen by leaving the implementation vague, so it 1570 was decided that clarifing at least a set of reccomendations, if not 1571 rising to the level of requirements, will help guide DTCP 1572 implementations and help ensure interoperability. 1574 Two possible cases of mismatch exist: when the client exceeds the 1575 server version, and when the server exceeds the client version. They 1576 are handled separately, but the motivation in each case is to permit 1577 maximum compatibility. 1579 In this case, versions are compared numerically, with a single digit 1580 after decimal point. For example: 0.4 is greater than 0.2, 1.9 is 1581 greater than 1.4, and 3.1 is greater than 2.9 1583 6.7.1. DTCP Client version exceeds DTCP Server version 1585 If the DTCP Client attempts to make a request to a DTCP Server using 1586 a DTCP version greater than that supported by the DTCP Server, the 1587 DTCP Server MUST return a "505 DTCP Version not supported" error 1588 message using the GREATEST DTCP version supported by the DTCP Server, 1589 and discontinue processing of that request. It has not way of 1590 knowing what new parameters might exist in a newer version of the 1591 protocol and simply has to abandon processing altogether. 1593 In this case, the onus is on the DTCP Client to revert to an older 1594 version of the protocol specification to talk with this DTCP Server 1595 to ensure that its request is properly handled. 1597 6.7.2. DTCP Server version exceeds DTCP Client version 1599 It is expected that a given DTCP Server will support a range of DTCP 1600 protocol specification versions, for interoperability purposes. 1602 If the DTCP Server receives a request from a DTCP Server using a DTCP 1603 version lesser than the most current version supported by the DTCP 1604 Server, the server SHOULD attempt to process that response using the 1605 semantics of the earlier specification, and MUST reply using the 1606 precise DTCP version included in the request. 1608 If the DTCP server is unable to do this, the DTCP Server MUST return 1609 a "505 DTCP Version not supported" error message using the LEAST DTCP 1610 version supported by the DTCP Server, and discontinue processing of 1611 that request 1613 Asynchronous Notifications sent to a client using an earlier version 1614 are addressed in Section 3.2 (Asynchronous Notifications). 1616 7. Message Payload Examples 1618 Note: These are only examples of message payloads, and are not 1619 intended to illustrate the full breadth of the protocol. Also, 1620 please note that the Authentication-Info shown are correct if each 1621 line is terminated with CRLF as specified and the key "secret" is 1622 used. (Terminating CRLFs are not shown.) 1624 7.1. Successful ADD Request and Response Payload 1626 Following is an example of the UDP payload for an Add request: 1628 ADD DTCP/0.6 1629 Source-Address: 192.168.10.4 1630 Dest-Address: 10.1.1.1-10.1.1.10 1631 Protocol: 6,17 1632 Dest-Port: 53 1633 Timeout-Idle: 600 1634 Action: Copy 1635 Priority: 2 1636 Flags: SendAsync 1637 Cdest-ID: cdst_b 1638 Csource-ID: csrc_a 1639 Seq: 3827443 1640 Authentication-Info: 28eb606458ba46160d7a59da48763020f5aef9f5 1642 Following is the UDP payload of one potential successful response to 1643 that Add request: 1645 DTCP/0.6 200 OK 1646 Criteria-ID: 38224 1647 Seq: 3827443 1648 Timestamp: 2005-01-01 12:01:01.111 1649 Authentication-Info: 38099d03fcb5b12a849b36f9bdccc757303fafd0 1651 7.2. Unsuccessful DELETE Request and Response Payload 1653 Following is an example of the UDP payload for an Delete request: 1655 DELETE DTCP/0.6 1656 Criteria-ID: 55331 1657 Csource-ID: csrc_d 1658 Flags: Static 1659 Seq: 2655371 1660 Authentication-Info: 6af62247a2b59a2a06e0ca08ec5a80a644e2cd67 1662 Following is the UDP payload of one potential unsuccessful response 1663 to that Delete request: 1665 DTCP/0.6 431 Unknown Criteria ID 1666 Criteria-ID: 55331 1667 Seq: 2655371 1668 Timestamp: 2005-02-02 12:02:02.222 1669 Authentication-Info: 5de4552e98832c2d2c3a9ffa8a2958c967b4e1e8 1671 This delete request was unsuccessful because the Criteria ID supplied 1672 did not exist. Note that the error-causing parameter is included 1673 within the reply to assist in debugging. 1675 8. Formal Syntax 1677 All of the mechanisms specified in this document are described in 1678 both prose and an Augmented Backus-Naur Form (ABNF) defined in RFC 1679 4234 [7]. Section 6.1 of RFC 4234 defines a set of core rules that 1680 are used by this specification, and not repeated here. Implementers 1681 need to be familiar with the notation and content of RFC 4234 in 1682 order to understand this specification. Certain basic rules are in 1683 uppercase, such as SP, LWS, HTAB, CRLF, DIGIT, ALPHA, etc. 1685 Note that while much of this syntax is taken from the Session 1686 Initiation Protocol (SIP), some of its constructs have been 1687 simplified for this application here. Where appropriate, these 1688 digressions have been noted with comments. 1690 The following core definitions appear throughout the formal syntax: 1692 COL = *(WSP) ":" *(WSP) ; used in parameter-value pair 1693 NPCHAR = "\" 3DIGIT ; used to express ctrl-chars 1694 DSTRING = *(VCHAR / NPCHAR) ; no embedded whitespace 1695 WC = "*" ; wildcard character for matching 1696 NOT = "!" ; invert character for matching 1697 N64BITNUM = 1*20DIGIT 1698 N32BITNUM = 1*10DIGIT 1699 N16BITNUM = 1*5DIGIT 1700 N8BITNUM = 1*3DIGIT 1701 DAYSEC = 1*5DIGIT 1702 IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT 1703 TEXT = 1*(1*(VCHAR) WSP) ; includes whitespace 1704 DTCP-Time = 4DIGIT "-" 2DIGIT "-" 2DIGIT SP 2DIGIT ":" 1705 2DIGIT ":" 2DIGIT "." 3DIGIT 1706 ; This is ISO date/time: YYYY-MM-DD sp HH:MM:SS.TTT 1708 Additionally, the following definitions are excerpted from RFC 3986 1709 [8]: 1711 IPv6address = 6( h16 ":" ) ls32 1712 / "::" 5( h16 ":" ) ls32 1713 / [ h16 ] "::" 4( h16 ":" ) ls32 1714 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 1715 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 1716 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 1717 / [ *4( h16 ":" ) h16 ] "::" ls32 1718 / [ *5( h16 ":" ) h16 ] "::" h16 1719 / [ *6( h16 ":" ) h16 ] "::" 1721 ls32 = ( h16 ":" h16 ) / IPv4address 1722 ; least-significant 32 bits of address 1724 h16 = 1*4HEXDIG 1725 ; 16 bits of address represented in hexadecimal 1727 Here begins the formal syntax: 1729 DTCP-Message = Request / Response / Notification 1731 Request = Request-Line 1732 ( Add-Req-Parameters 1733 / Delete-Req-Parameters 1734 / Refresh-Req-Parameters 1735 / List-Req-Parameters 1736 / Noop-Req-Parameters) 1737 *(extension-parameter) 1738 Csource-ID 1739 Seq 1740 Authentication-Info 1741 CRLF 1743 Response = Status-Line 1744 ( ( Add-Resp-Parameters 1745 / Delete-Resp-Parameters 1746 / Refresh-Resp-Parameters 1747 / List-Resp-Parameters 1748 / Noop-Resp-Parameters) / Error-Parameters ) 1749 *(extension-parameter) 1750 Timestamp 1751 Seq ; note absence of Csource-ID 1752 Authentication-Info 1753 CRLF 1755 Notification = Status-Line 1756 ( Restart-Notif-Parameters 1757 / Rollover-Notif-Parameters 1758 / Noop-Notif-Parameters 1759 / Timeout-Notif-Parameters 1760 / Congestion-Notif-Parameters 1761 / CongDel-Notif-Parameters ) 1762 *(extension-parameter) 1763 Timestamp 1764 Authentication-Info ; note absence of Seq 1765 CRLF 1767 DTCP-Version = "DTCP" "/" 1*DIGIT "." 1*DIGIT 1769 Status-Line = DTCP-Version SP Status-Code SP Reason-Phrase CRLF 1770 Request-Line = Method SP DTCP-Version CRLF 1772 Method = "ADD" / "DELETE" / "REFRESH" / "LIST" / "NOOP" 1773 / extension-method 1775 extension-method = DSTRING 1777 Status-Code = Provisional 1778 / Success 1779 / Redirection 1780 / Request-Failure 1781 / Server-Failure 1782 / Global-Failure 1783 / extension-code 1785 Reason-Phrase = TEXT ; differs from SIP 1786 extension-code = 3DIGIT 1788 Provisional = "130" ; Sequence Number Rollover (Notif) 1789 / "131" ; NoOp Notification (Notif) 1790 Success = "200" ; OK 1791 Redirection = "390" ; Criterion Timeout Delete (Notif) 1792 Request-Failure = "400" ; Bad Request 1793 / "430" ; Unknown Content Destination 1794 / "431" ; Unknown Criteria ID 1795 / "432" ; Improper Filter Specification 1796 / "433" ; Improper Timeout Specification 1797 / "497" ; Invalid Authentication 1798 ; (never sent to client) 1799 / "498" ; Invalid Sequence Number 1800 ; (never sent to client) 1801 / "499" ; Unknown Control Source Identifier 1802 ; (never sent to client) 1803 Server-Failure = "500" ; Server Internal Error 1804 / "501" ; Not Implemented 1805 / "505" ; DTCP Version not supported 1806 / "550" ; Max Criteria Limit Exceeded 1807 / "551" ; Max Content Destination Exceeded 1808 / "580" ; Congestion (Notif) 1809 / "598" ; Duplicate Packets Dropped (Notif) 1810 / "599" ; Server Restart (Notif) 1811 Global-Failure = "680" ; Criterion Congestion Delete (Notif) 1813 Error-Parameters = Cdest-ID 1814 / Criteria-ID 1815 / Filter-Block 1816 / Timeout-Block 1818 Add-Req-Parameters = Filter-Block Timeout-Block [Action] 1819 Option-Block [Flags] Cdest-ID 1821 Filter-Block = *(Filter-Element) 1822 Timeout-Block = *(Timeout-Element) 1823 TRemaining-Block = *(TRemaining-Element) 1824 Option-Block = *(Option-Element) 1825 Timeout-Required-Block = 1*(Timeout-Element) 1826 TRemaining-Required-Block = 1*(TRemaining-Element) 1828 Filter-Element = Source-Address 1829 / Dest-Address 1830 / Protocol 1831 / Source-Port 1832 / Dest-Port 1833 / ICMP-Type 1834 / ICMP-Code 1836 Timeout-Element = Timeout-Idle 1837 / Timeout-Total 1838 / Timeout-Packets 1839 / Timeout-Bytes 1841 TRemaining-Element = Remaining-Idle 1842 / Remaining-Total 1843 / Remaining-Packets 1844 / Remaining-Bytes 1846 Option-Element = Priority 1848 Add-Resp-Parameters = Criteria-ID 1850 Delete-Req-Parameters = ( (Criteria-ID / Criteria-ID-Filter) 1851 Cdest-ID ) [Flags] 1852 Delete-Resp-Parameters = Criteria-Count 1854 Refresh-Req-Parameters = ( (Criteria-ID / Criteria-ID-Filter) 1855 Cdest-ID ) Timeout-Required-Block 1856 Refresh-Resp-Parameters = Criteria-Count 1858 List-Req-Parameters = [ ( (Criteria-ID / Criteria-ID-Filter) 1859 Cdest-ID ) ] [Flags] 1861 List-Resp-Parameters = *(List-Resp-Entry CRLF) 1863 List-Resp-Entry = Criteria-Count Criteria-Num Main-List 1864 [Criteria-List] [Stats-List] 1866 Main-List = Csource-ID Csource-Address Cdest-ID 1867 Criteria-ID Timestamp 1868 Criteria-List = *(Filter-Element) *(Timeout-Element) [Flags] 1869 Stats-List = TRemaining-Block Stats-Block 1871 Stats-Block = Average-Bandwidth Matching-Packets 1872 Matching-Bytes Num-Refresh Last-Refresh 1874 Noop-Req-Parameters = [Flags] 1875 Noop-Resp-Parameters = [] ; no parameters 1877 Restart-Notif-Parameters = Alert-Info 1878 Rollover-Notif-Parameters = [] ; no parameters 1879 Noop-Notif-Parameters = [] ; no parameters 1880 Timeout-Notif-Parameters = Criteria-ID 1881 / Timeout-Required-Block 1882 / TRemaining-Required-Block 1883 Congestion-Notif-Parameters = Cdest-ID Average-Bandwidth 1884 Alert-Bandwidth Max-Bandwidth 1885 CongDel-Notif-Parameters = Cdest-ID Criteria-ID-Filter 1887 extension-parameter = "X-" DSTRING COL DSTRING CRLF 1889 Csource-ID = "Csource-ID" COL DSTRING CRLF 1890 Seq = "Seq" COL N64BITNUM CRLF 1891 Authentication-Info = "Authentication-Info" COL 40HEXDIG CRLF 1892 ID-List = DSTRING *("," DSTRING) 1893 Cdest-ID = "Cdest-ID" COL ID-List CRLF 1894 Source-Address = "Source-Address" COL IPFilter CRLF 1895 Dest-Address = "Dest-Address" COL IPFilter CRLF 1896 Protocol = "Protocol" COL ProtFilter CRLF 1897 Source-Port = "Source-Port" COL PortFilter CRLF 1898 Dest-Port = "Dest-Port" COL PortFilter CRLF 1899 ICMP-Type = "ICMP-Type" COL ICMPFilter CRLF 1900 ICMP-Code = "ICMP-Code" COL ICMPFilter CRLF 1901 Timeout-Idle = "Timeout-Idle" COL DAYSEC CRLF 1902 Timeout-Total = "Timeout-Total" COL DAYSEC CRLF 1903 Timeout-Packets = "Timeout-Packets" COL N32BITNUM CRLF 1904 Timeout-Bytes = "Timeout-Bytes" COL N64BITNUM CRLF 1905 Priority = "Priority" COL N8BITNUM CRLF 1906 Criteria-ID = "Criteria-ID" COL N32BITNUM CRLF 1907 Criteria-ID-Filter = "Criteria-ID" COL CritFilter CRLF 1908 Criteria-Count = "Criteria-Count" COL N32BITNUM CRLF 1909 Criteria-Num = "Criteria-Num" COL N32BITNUM CRLF 1910 Csource-Address = "Csource-Address" COL (IPv4address / 1911 IPv6address) CRLF 1912 Timestamp = "Timestamp" COL DTCP-Time CRLF 1913 Remaining-Idle = "Remaining-Idle" COL DAYSEC CRLF 1914 Remaining-Total = "Remaining-Total" COL DAYSEC CRLF 1915 Remaining-Packets = "Remaining-Packets" COL N32BITNUM CRLF 1916 Remaining-Bytes = "Remaining-Bytes" COL N64BITNUM CRLF 1917 Average-Bandwidth = "Average-Bandwidth" COL N64BITNUM CRLF 1918 Matching-Packets = "Matching-Packets" COL N64BITNUM CRLF 1919 Matching-Bytes = "Matching-Bytes" COL N64BITNUM CRLF 1920 Num-Refresh = "Num-Refresh" COL N32BITNUM CRLF 1921 Last-Refresh = "Last-Refresh" COL DTCP-Time CRLF 1922 Alert-Info = "Alert-Info" COL TEXT CRLF 1923 Alert-Bandwidth = "Alert-Bandwidth" COL N64BITNUM CRLF 1924 Max-Bandwidth = "Max-Bandwidth" COL N64BITNUM CRLF 1925 Action = "Action" COL ActionEntry CRLF 1927 ActionEntry = "Copy" 1928 / "Block" 1929 / "Redirect" 1930 / extension-action 1932 extension-action = DSTRING 1933 Flags = "Flags" COL FlagEntry *("," FlagEntry) CRLF 1935 FlagEntry = "Static" 1936 / "SendAsync" 1937 / "Stats" 1938 / "Criteria" 1939 / "Both" 1941 IPFilter = [NOT] IPEntry *("," [WSP] [NOT] IPEntry) 1943 ProtFilter = [NOT] ProtEntry *("," [WSP] [NOT] ProtEntry) 1945 PortFilter = [NOT] PortEntry *("," [WSP] [NOT] PortEntry) 1947 ICMPFilter = [NOT] ICMPEntry *("," [WSP] [NOT] ICMPEntry) 1949 CritFilter = [NOT] CritEntry *("," [WSP] [NOT] CritEntry) 1951 IPEntry = IPv4Entry 1952 / IPv6Entry 1954 IPv4Entry = IPv4address ; Single Entry 1955 / IPv4address "/" N8BITNUM ; Address/mask 1956 / IPv4address "-" IPv4address ; Range 1957 / IPv4address "-" WC ; Range to UBOUND 1958 / WC "-" IPv4address ; LBOUND to Range 1959 / WC ; Pure Wildcard 1961 IPv6Entry = IPv6address ; Single Entry 1962 / IPv6address "/" N8BITNUM ; Address/mask 1963 / IPv6address "-" IPv6address ; Range 1964 / IPv6address "-" WC ; Range to UBOUND 1965 / WC "-" IPv6address ; LBOUND to Range 1966 / WC ; Pure Wildcard 1968 PortEntry = N16BITNUM ; Single Entry 1969 / N16BITNUM "-" N16BITNUM ; Range 1970 / N16BITNUM "-" WC ; Range to UBOUND 1971 / WC "-" N16BITNUM ; LBOUND to Range 1972 / WC ; Pure Wildcard 1974 ProtEntry = N8BITNUM ; Single Entry 1975 / N8BITNUM "-" N8BITNUM ; Range 1976 / N8BITNUM "-" WC ; Range to UBOUND 1977 / WC "-" N8BITNUM ; LBOUND to Range 1978 / WC ; Pure Wildcard 1980 ICMPEntry = N8BITNUM ; Single Entry 1981 / N8BITNUM "-" N8BITNUM ; Range 1982 / N8BITNUM "-" WC ; Range to UBOUND 1983 / WC "-" N8BITNUM ; LBOUND to Range 1984 / WC ; Pure Wildcard 1986 CritEntry = N64BITNUM ; Single Entry 1987 / N64BITNUM "-" N64BITNUM ; Range 1988 / N64BITNUM "-" WC ; Range to UBOUND 1989 / WC "-" N64BITNUM ; LBOUND to Range 1990 / WC ; Pure Wildcard 1992 9. Security Considerations 1994 DTCP empowers network security personnel to monitor packet data 1995 transitioning through a network element. As such, it is a powerful 1996 protocol that can cause any network data to be redirected to a 1997 arbitrary location for inspection. Consequently, it is of greatest 1998 criticality that any DTCP Servers fully implement the security model 1999 outlined in this draft. Failure to do so could result in malicious 2000 individuals either obtaining unauthorized access to data or 2001 interruption of data transmission. 2003 10. IANA Considerations 2005 This document has no actions for IANA. 2007 11. Conclusions 2009 This protocol has undergone extensive testing and several rounds of 2010 refinements. The resulting protocol is highly effective at meeting 2011 its goals of providing a real-time mechanism to inspect raw packets 2012 containing security-related events traversing a network in real-time. 2014 12. Acknowledgements 2016 Thanks to all at ATT and Juniper Networks who provided testing and 2017 support for this experimental protocol! 2019 The authors would specifically like to thank Joju Chevookaran and 2020 Saravanan Deenadayalan from Juniper since they have not only 2021 workedhard on the implementation, but also on the some of the 2022 enhancements (specially VRF support, input/out interface filters 2023 etc). 2025 Also, Rick Suntag, Michael Nanashko, and Michael St. Angelo from ATT 2026 all deserve special note for extensive testing as well as excellent 2027 protocol definition suggestions and corrections. 2029 13. References 2031 [RFC1945] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext 2032 Transfer Protocol -- HTTP/1.0", RFC 1945, 2033 DOI 10.17487/RFC1945, May 1996, 2034 . 2036 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2037 Hashing for Message Authentication", RFC 2104, 2038 DOI 10.17487/RFC2104, February 1997, 2039 . 2041 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2042 Requirement Levels", BCP 14, RFC 2119, 2043 DOI 10.17487/RFC2119, March 1997, 2044 . 2046 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2047 A., Peterson, J., Sparks, R., Handley, M., and E. 2048 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2049 DOI 10.17487/RFC3261, June 2002, 2050 . 2052 Appendix A. Prior Implementation 2054 This document fully and accurately describes the operation of 2055 DTCP/0.7 implementations. However, in development of this protocol, 2056 some implementations with working versions of the protocol were 2057 released. This appendix describes the differences between the 2058 DTCP/0.7 protocol specification documented herein and the prior 2059 DTCP/0.5 and DTCP/0.6 protocol specifications. 2061 Other than the changes documented in this appendix, the older 2062 protocol specifications precisely follow DTCP/0.7 described herein. 2063 This appendix is provided for backward-compatibility purposes only; 2064 all new implementations should ignore this appendix. 2066 A.1. Version Number 2068 (Modifies section 6.4 Current Version) 2070 o The prior supported version string was exactly: DTCP/0.6 2072 A.2 Response to List Request 2073 (Modifies sections 5.11 List Response, 6.1 Special treatment of 2074 response to List request and 8 Formal Syntax) 2076 The following changes apply only to the elements involved in the 2077 Response message used in reply to the List action. Changes are both 2078 syntactic and semantic in nature. 2080 o The ABNF element called "Criteria-Num" in DTCP/0.7 did not exist 2081 in DTCP/0.5 and was not included in any DTCP message. 2083 o The ABNF element called "Criteria-Count" in DTCP/0.7 was called 2084 "Num-Criteria" in DTCP/0.5. 2086 o The "Num-Criteria" element was only included in the final UDP 2087 packet sent. This signals the end of the List response. 2089 A.3 Changes in response Codes 2091 1. 550: Max Criteria Limit Exceeded 2093 This error message is sent when the number of DTCP ADD requests 2094 received by the server exceeds the allowed limit. Error code 500 2095 used in the earlier Flow-Tap implementations was not clear enough. 2097 2. 551: Max Content Destination Exceeded 2099 Server allows only a certain number of Content Destinations at any 2100 given time, and generates this error message when the server receives 2101 a DTCP ADD request that contains a new content destination after the 2102 number of Content Destinations on that server has already exceeded 2103 the allowable limit. 2105 3. 432: Improper Filter Specification 2107 Generated when an ADD request contains a combination of X-JTap-VRF- 2108 Name, X-JTap-Input-Interface, and X-JTap-Output-Interface fields. 2110 A.4. IP Version 6 2112 The formal ABNF syntax has been updated to include IP Version 6 in 2113 parallel with IP Version 4 both in the filter criteria specification 2114 as well as ancillary addressing information. The intent was to 2115 permit the protocol to operate largely unmodified while allowing the 2116 use of IP Version 6 addressing information. Some implementations may 2117 not support this addressing mode. 2119 A.5. Sequence Number Negative Window 2120 The Negative Window sequence number concept has been added to this 2121 version of DTCP to address empirical errors found when testing with a 2122 high rate of DTCP "ADD" messages over a non-trivial network. 2124 A.6. Version Mismatches 2126 The section on Version Mismatches was added, to account for specific 2127 problems encountered during upgrade of either the client or the 2128 server. In particular, the draft was ambiguous on how the DTCP 2129 Server should behave when servicing clients of various versions. 2131 Appendix B. DTCP Vendor-Specific Extension 2133 B.1.1 Flow-Tap DTCP Extensions 2135 In support of Flow-Tap functionality, the DTCP grammar has been 2136 extended to include new parameters defined below. In general, the 2137 purpose of these parameters is to allow a content destination to be 2138 configured on-demand, rather than pre-configured. General DTCP 2139 grammar does not provide this functionality, so we extend it herein. 2141 Note that "JTap-Failure" below is not a grammar tag; it just defines 2142 a new error value "901' that will be used to indicate any problems 2143 with the X-JTap parameters. 2145 1. X-JTap-Cdest-Dest-Address 2147 IP address(es) of Content destination(s) where the matching packets 2148 need to be sent out. User may specify maximum two IP addresses 2149 separated by a comma. This field MUST be present in the ADD request 2150 otherwise "JTAP-Failure" error will be generated. 2152 2. X-JTap-Cdest-Dest-Port 2154 UDP port number(s) of Content destination(s) where the matching 2155 packets need to be sent out. User may specify maximum two port 2156 numbers separated by a comma. This field MUST be present in the ADD 2157 request otherwise "JTAP-Failure" error will be generated. 2159 3. X-JTap-Cdest-TTL 2161 TTL value to be used in the forwarded packet. This is an optional 2162 field and default of 255 will be used if not specified 2164 4.X-JTap-Cdest-Source-Address 2165 Source IP address from which the forwarded packet needs to besent 2166 from This field MUST be present in the ADD request and "JTap-Failure" 2167 error will be generated if this is not specified 2169 5. X-JTap-Cdest-Source-Port 2171 Source UDP port from which the forwarded packet needs to be sent from 2173 This field MUST be present in the ADD request and "JTap-Failure" 2174 error will be generated if this is not specified. 2176 6. Changes in Cdest-ID 2178 Cdest-ID field enables you to specify more than one content 2179 destination by using a comma separated list. Currently, only two 2180 content destinations are supported. However, note that the number of 2181 entries in all the three fields, Cdest-ID, X-JTap-Cdest-Dest-Address 2182 and X-JTap-Cdest-Dest-Port, must be the same. That is, if you have 2183 only one entry in one of the fields, the other two can have only one 2184 entry each. Error message 432 is generated if the number of entries 2185 in these fields does not match with each other. 2187 7. X-JTap-VRF-Name 2189 OPTIONAL field to specify a VRF name. If it is specified, only the 2190 packets coming to the specified VRF will be monitored. "JTap- 2191 Failure" error will be generated if the VRF is not configured 2193 8. X-JTap-Input-Interface 2195 OPTIONAL field to specify a list of interfaces. If it is specified, 2196 it will be attached to respective input interface(s) instead of 2197 global Flow-Tap filters. This list may contain maximum 8 interfaces 2198 separated by comma. If the unit name of an interface is not 2199 specified, System will assume it as unit 0. "JTap-Failure" error 2200 will be generated if any one of the interfaces in the list is not 2201 configured 2203 9. X-JTap-Output-Interface 2205 OPTIONAL field to specify a list of interfaces. If it is specified, 2206 the filter will be attached to respective output interface(s) instead 2207 of global Flow-Tap filters. This list may contain maximum 8 2208 interfaces separated by comma. If the unit name of an interface is 2209 not specified, System will assume it as unit 0. "JTap-Failure" error 2210 will be generated if any one of the interfaces in the list is not 2211 configured 2212 B.1.2 "Flow-Tap" extension ABNF 2214 IP-4-OR-6 = (IPv4address / IPv6address) 2215 ADDR-LIST = IP-4-OR-6 1*("," IP-4-OR-6) 2216 PORT-LIST = N16BITNUM 1*("," N16BITNUM) 2217 IFL = 3CHAR "-" 2*DIGIT "/" 1*DIGIT "/" 1*DIGIT ["." N16BITNUM] 2218 IFL-LIST8 = IFL 7*("," IFL) 2220 X-JTap-Cdest-Dest-Address = "X-JTap-Cdest-Dest-Address" COL ADDR-LIST 2221 CRLF 2222 X-JTap-Cdest-Dest-Port = "X-JTap-Cdest-Dest-Port" COL PORT-LIST 2223 CRLF 2224 X-JTap-Cdest-TTL = "X-JTap-Cdest-TTL" COL N8BITNUM CRLF 2225 X-JTap-Cdest-Source-Address = "X-JTap-Cdest-Source-Address" COL 2226 (IPv4address / IPv6address) CRLF 2227 X-JTap-Cdest-Source-Port = "X-JTap-Cdest-Source-Port" COL N16BITNUM 2228 CRLF 2229 X-JTap-VRF-Name = "X-JTap-VRF-Name" COL DSTRING 2230 CRLF 2231 X-JTap-Input-Interface = "X-JTap-Input-Interface" COL IFL-LIST8 2232 CRLF 2233 X-JTap-Output-Interface = "X-JTap-Output-Interface" COL IFL-LIST8 2234 CRLF 2236 Figure 3 2238 Authors' Addresses 2240 Sumit Kala 2241 Juniper Networks 2242 Flat #202, Propulsive Pride Apartment, Doddakannelli Road 2243 Bangalore, Karnataka 560035 2244 INDIA 2246 Phone: +91 8197477794 2247 Email: sumitk@juniper.net 2249 David Cavuto 2250 ATT 2252 Email: cavuto@att.net