idnits 2.17.1 draft-kala-dtcp-02.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: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 3) being 60 lines 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 12 instances of too long lines in the document, the longest one being 8 characters in excess of 72. == 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 (June 28, 2017) is 2492 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 142 -- Looks like a reference, but probably isn't: '3' on line 553 == Missing Reference: '0-9a-f' is mentioned on line 555, but not defined -- Looks like a reference, but probably isn't: '4' on line 555 == Missing Reference: 'Criteria' is mentioned on line 1095, but not defined == Missing Reference: 'Stats' is mentioned on line 1123, but not defined -- Looks like a reference, but probably isn't: '7' on line 1662 -- Looks like a reference, but probably isn't: '8' on line 1692 == Unused Reference: 'RFC5938' is defined on line 2031, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1945 ** Downref: Normative reference to an Informational RFC: RFC 2104 Summary: 4 errors (**), 0 flaws (~~), 7 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: December 28, 2017 ATT 6 June 28, 2017 8 DTCP: Dynamic Tasking Control Protocol 9 draft-kala-dtcp-02 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 December 28, 2017. 43 Copyright Notice 45 Copyright (c) 2017 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 (http://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Operational Modes . . . . . . . . . . . . . . . . . . . . 4 61 1.2. Performance Considerations . . . . . . . . . . . . . . . . 4 62 1.3. Conventions used in this document . . . . . . . . . . . . 5 63 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.3. Control Source . . . . . . . . . . . . . . . . . . . . . . 5 67 2.4. Content Destination . . . . . . . . . . . . . . . . . . . 5 68 2.5. Criteria . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3. Overview of Operation . . . . . . . . . . . . . . . . . . . . 6 70 3.1. Request-Response Paradigm . . . . . . . . . . . . . . . . 6 71 3.2. Asynchronous Notifications . . . . . . . . . . . . . . . . 7 72 3.3. Data Delivery Mechanism . . . . . . . . . . . . . . . . . 8 73 4. Security Model . . . . . . . . . . . . . . . . . . . . . . . . 9 74 4.1. No Information Exposure . . . . . . . . . . . . . . . . . 9 75 4.2. Independence of Control Sources . . . . . . . . . . . . . 9 76 4.3. Control Source to Content Destination Access Control . . . 9 77 4.4. Per-Message Security Mechanisms . . . . . . . . . . . . . 9 78 4.4.1. Sequence Number . . . . . . . . . . . . . . . . . . . 9 79 4.4.1.1. Sequence Number Negative Window . . . . . . . . . 10 80 4.4.2. Hashing Message Authentication Code (HMAC) . . . . . . 11 81 5. Application-Layer Message Formats . . . . . . . . . . . . . . 12 82 5.1. Request General Format . . . . . . . . . . . . . . . . . . 13 83 5.2. Response General Format . . . . . . . . . . . . . . . . . 13 84 5.3. Notification General Format . . . . . . . . . . . . . . . 13 85 5.4. Add Request . . . . . . . . . . . . . . . . . . . . . . . 14 86 5.4.1. Criteria Timeouts . . . . . . . . . . . . . . . . . . 15 87 5.5. Add Response . . . . . . . . . . . . . . . . . . . . . . . 16 88 5.6. Delete Request . . . . . . . . . . . . . . . . . . . . . . 17 89 5.7. Delete Response . . . . . . . . . . . . . . . . . . . . . 18 90 5.8. Refresh Request . . . . . . . . . . . . . . . . . . . . . 19 91 5.9. Refresh Response . . . . . . . . . . . . . . . . . . . . . 20 92 5.10. List Request . . . . . . . . . . . . . . . . . . . . . . . 21 93 5.11. List Response . . . . . . . . . . . . . . . . . . . . . . 21 94 5.12. NoOp Request . . . . . . . . . . . . . . . . . . . . . . . 23 95 5.13. NoOp Response . . . . . . . . . . . . . . . . . . . . . . 24 96 5.14. Restart Notification . . . . . . . . . . . . . . . . . . . 24 97 5.15. Rollover Notification . . . . . . . . . . . . . . . . . . 24 98 5.16. NoOp Notification . . . . . . . . . . . . . . . . . . . . 24 99 5.17. Timeout Notification . . . . . . . . . . . . . . . . . . . 25 100 5.18. Congestion Notification . . . . . . . . . . . . . . . . . 25 101 5.19. CongestionDelete Notification . . . . . . . . . . . . . . 26 102 5.20. DuplicatesDropped Notification . . . . . . . . . . . . . . 26 103 6. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 27 104 6.1. Special treatment of response to List request . . . . . . 27 105 6.2. Error or Exception Conditions . . . . . . . . . . . . . . 29 106 6.3. Extensions in ABNF . . . . . . . . . . . . . . . . . . . . 30 107 6.4. Current Version . . . . . . . . . . . . . . . . . . . . . 30 108 6.5. No specific port . . . . . . . . . . . . . . . . . . . . . 30 109 6.6. Unimplemented Protocol Methods and Parameters . . . . . . 31 110 6.7. Version Mismatches . . . . . . . . . . . . . . . . . . . . 31 111 6.7.1. DTCP Client version exceeds DTCP Server version . . . 32 112 6.7.2. DTCP Server version exceeds DTCP Client version . . . 32 113 7. Message Payload Examples . . . . . . . . . . . . . . . . . . . 32 114 7.1. Successful ADD Request and Response Payload . . . . . . . 33 115 7.2. Unsuccessful DELETE Request and Response Payload . . . . . 33 116 8. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 34 117 9. Security Considerations . . . . . . . . . . . . . . . . . . . 40 118 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 119 11. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 41 120 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41 121 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 122 Appendix A. Prior Implementation . . . . . . . . . . . . . . . . . 42 123 Appendix B. DTCP Vendor-Specific Extension . . . . . . . . . . . . 43 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 126 1. Introduction 128 The Dynamic Tasking Control Protocol (DTCP) is a mechanism used to 129 dynamically control network elements in the course of performing a 130 security or other analysis on a transient network event. 132 Network Security personnel typically have little visibility into the 133 very networks they are monitoring. Routers and switches have awkward 134 mechanisms such as port mirroring and cFlowd to enable personnel some 135 meager view into the traffic flowing through a device. 137 However, when a security incident does happen to be detected, the 138 security analysis staff struggles to gain more insight as to the 139 actual content of the incident, via inference from these tools. This 140 is a time-consuming and cumbersome task. 142 cFlowd [9] and other aggregation mechanisms provide only session- 143 level statistics about the event, and fail to provide any view into 144 the actual packet data. In contrast, wholesale backhauling of port- 145 mirrored data is often cumbersome (and expensive) to set up, since it 146 requires pre-provisioned free bandwidth on wide-area links, and often 147 additional network hardware to implement. 149 The intent of DTCP is to provide a simple mechanism by which a third- 150 party device can interact with a network element or security policy- 151 enforcement-point (PEP) that normally processes packetized network 152 data, and in that interaction cause the PEP to take some action 153 (usually copy) on a defined subset of that packet data to be 154 forwarded for further inspection and analysis. 156 packet +---+ packet 157 data ->---|NE |--->- data 158 +---+ 159 ^ | 160 | | 161 DTCP ----+ +---> copy of selected packet data 163 Figure 1 - DTCP interacting with a network element. 165 The Network Element (NE) or PEP may be a firewall or proxy server, or 166 some other non-security-specific network element, such as a router or 167 a switch. This is illustrated in Figure 1. 169 1.1. Operational Modes 171 The primary operation in DTCP is the specification of the filter 172 criteria used to select or filter packets. DTCP is designed to work 173 in an IPv4 environment, and accordingly all selection criteria are 174 chosen from IPv4 and higher-layer protocol definitions. Note that 175 current DTCP syntax is limited to L3 and L4, but could be expanded to 176 higher layers. Basic filter criteria definitions have semantic (if 177 not syntactic) similarity to well-known router access-control lists 178 (ACLs) or firewall rulesets. 180 The primary operational mode of DTCP is the "copy" mode, whereby the 181 controlled network element forwards the packet towards its intended 182 destination, and also makes a copy of that packet, which it forwards 183 towards a preconfigured collection and analysis center. In this 184 mode, the original packet flow is not interrupted. DTCP makes no 185 provisions for the potential performance impact on the network 186 element when performing this function; obviously a negligible impact 187 is most desirable. 189 DTCP also supports optional modes for purely redirecting the packet 190 data (instead of making a copy of it), as well as blocking packet 191 data. These modes, if implemented, can provide additional 192 functionality for network security personnel, who may have decided 193 that particular traffic is disallowed on the network and wishes to 194 interrupt the selected flow of traffic. 196 Of critical distinction to DTCP is the basic paradigm that DTCP does 197 NOT involve a "reprovisioning" or "reconfiguration" of the controlled 198 device. DTCP is by its very nature transient; controlled devices 199 should not attempt to maintain DTCP state in a non-volatile storage 200 system. 202 1.2. Performance Considerations 203 It is envisioned that the controlling side of DTCP will be 204 implemented by both human-interactive systems and automated systems. 205 Since controlled Network Element MUST be able to respond to automated 206 requests at a potentially high rate (due to floods or other attacks), 207 the protocol implies a high performance requirement during the 208 "criteria specification" phase of the interaction. In particular, 209 the response time of the Network Element to respond to the DTCP 210 request to monitor data is of considerable importance, as the traffic 211 intended to be monitored may be short-lived. 213 While concrete performance requirements are outside the scope of this 214 document, implementers are urged to focus performance on this part of 215 the client-server interaction. 217 1.3. Conventions used in this document 219 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 220 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 221 document are to be interpreted as described in RFC 2119 [RFC2119]. 223 2. Definitions 225 The following sections define terms that have special significance 226 within the DTCP context. 228 2.1. Server 230 The DTCP Server is the PEP or network element that controls the data 231 of interest. The DTCP Server will be controlled in turn via DTCP. 232 The Server is responsible for maintaining state of DTCP Client 233 Requests, and forwarding data accordingly. Usually the DTCP Server 234 will be implemented on a firewall or router (or an accessory device 235 attached to one). The Server generally Responds to Requests, and can 236 also initiate Asynchronous Notifications. One Server generally 237 services more than one Client. 239 2.2. Client 241 The DTCP Client is an arbitrary host that initiates Requests to the 242 Server via DTCP. 244 2.3. Control Source 246 A Control Source is the instantiation of one DTCP Client, with 247 respect to a given Server. Each Control Source is preconfigured and 248 pre-authorized on a given Server to be able to interact with it via 249 DTCP. Control Sources may also receive Asynchronous Notifications. 250 There may be many Control Sources configured on a given Server. A 251 Control Source MUST NOT be identified by IP address; rather, Control 252 Sources are identified by user-configured character strings. 254 2.4. Content Destination 255 A Content Destination is the recipient of the extracted data, once it 256 is forwarded by the server. Content Destinations are also 257 preconfigured on the server. A Content Destination MUST NOT be 258 identified by IP address; rather, Content Destinations are identified 259 by user-configured character strings. 261 2.5. Criteria 263 The Criteria is the list of matching conditions under which a packet 264 is selected and acted upon by the server. Criteria are specified in 265 requests from the client to the server, which maintains a list of 266 active criteria for each client. 268 3. Overview of Operation 270 This section describes the basic interaction between the DTCP 271 elements, as well as the protocol message flows. 273 3.1. Request-Response Paradigm 275 The basic model for DTCP is a request-response message exchange 276 paradigm, where the server waits for messages on a specific UDP port 277 from authorized Control Sources. When a request message arrives, the 278 server processes the request, performs the necessary internal state 279 change as per the request, and then sends a reply message. 281 Note that although DTCP is specified as a message-based protocol, it 282 is designed and specified here to operate via single UDP/IP packets, 283 for performance reasons. While it is certainly possible for DTCP to 284 be operated over TCP/IP for reliable connections, such use is 285 unexplored as yet, and any implementation-specific decisions made are 286 unspecified herein. This document is written assuming that UDP will 287 be used as the Layer-4 transport mechanism. 289 A DTCP Server MUST allocate at least ONE IP address and ONE UDP port 290 for inbound connections from clients. Each DTCP Client MUST be 291 statically configured with at least ONE IP address and ONE UDP port 292 representing the server. 294 There is no mechanism defined that ensures proper configuration 295 between DTCP Clients and servers for requests and responses. 297 In general, each request and each reply are a single UDP message, 298 contained within a single IP packet. Since IP packets may be 299 fragmented during delivery, each DTCP endpoint MUST be capable of IP 300 fragment reassembly. 302 An IP packet containing a DTCP Request message from a client to a 303 server MUST have the following attributes properly set: 305 1. Destination IP Address MUST equal an IP address of a DTCP Server; 307 2. IP Protocol MUST equal 17 (UDP); 308 3. Destination UDP Port MUST equal a UDP port being listened on by 309 the respective DTCP Server. 311 The DTCP Server MUST NOT rely on the source IP address or source UDP 312 port of inbound request packets for any identification or 313 authentication of the message. 315 An IP packet containing a DTCP Reply message from a server to a 316 client MUST have the following attributes properly set: 318 1. Source IP Address MUST equal the Destination IP Address of the IP 319 packet containing the Request; 321 2. Destination IP address MUST equal the Source IP Address of the IP 322 packet containing the Request; 324 3. IP Protocol MUST equal 17 (UDP); 326 4. Destination UDP port MUST equal the Source UDP port of the UDP 327 message containing the Request; 329 5. Source UDP port MUST equal the Destination UDP port of the UDP 330 message containing the Request. 332 There is no specific UDP port registered for DTCP; rather, each DTCP 333 Server SHOULD permit the user to configure the port or set of ports 334 on which it will listen for inbound DTCP requests. Additionally, a 335 DTCP Server MAY choose to implement address or other filters on the 336 source of inbound client requests; however, this is optional and 337 implementation specific. (Recall that clients are identified by 338 strings, NOT IP addresses.) 340 3.2. Asynchronous Notifications 342 Notifications are sent out by the DTCP Server to a set of statically 343 preconfigured DTCP Clients who wish to receive notifications of 344 asynchronous events. Such messages are sent to IP addresses that 345 have been preconfigured therein. 347 A DTCP Client MAY provide a mechanism for accepting and processing 348 Notifications. The DTCP Server MUST be preconfigured with an IP 349 address and UDP port for each DTCP Client that wishes to receive 350 Notifications. 352 There is no mechanism defined that ensures proper configuration 353 between DTCP Clients and servers for Notifications. 355 An IP packet containing a DTCP Notification message from a server to 356 a client MUST have the following attributes properly set: 358 1. Destination IP address MUST equal the configured DTCP Client IP 359 address; 361 2. IP Protocol MUST equal 17 (UDP); 363 3. Destination UDP port MUST equal the configured DTCP Client UDP 364 port. 366 A future enhancement to this document may be to provide a mechanism 367 for clients to dynamically self-register for notifications. 369 A DTCP Server SHOULD include a configuration parameter for each 370 configured Control Source to indicate the Notification Version for 371 that Control Source. If such a parameter is configured for a given 372 Control Source, all Asynchronous Notifications sent from the DTCP 373 Server to that Control Source MUST precisely match the Notification 374 Version configured for that Control Source. Additionally, if such a 375 parameter is configured for a given Control Source, the DTCP Server 376 MUST NOT send Asynchronous Notifications to that Control Source that 377 do not exist in the DTCP specification indicated for that Control 378 Source. Finally, the DTCP Server MUST ensure that Asynchronous 379 Notifications whose formats have been modified in newer versions of 380 DTCP are properly formatted to meet the older DTCP specification 381 version indicated for that Control Source. 383 Note that in general the DTCP Server SHOULD accept requests from a 384 DTCP Client using a DTCP Version other than that specified in the 385 Notification Version for that client. 387 If the DTCP Server is unable to meet these requirements, upon 388 receiving a request from a DTCP Client with a mismatching version, it 389 MUST return a a "505 DTCP Version not supported" error message *using 390 the highest version supported by the DTCP Server*, and discontinue 391 processing of that request. 393 It is recommended, however, that the DTCP Server reject such a state 394 at configuration time rather than at run time. 396 3.3. Data Delivery Mechanism 398 Since the original packet IP header is not originally addressed to 399 the intended Content Destination, each DTCP Server implementation 400 MUST provide a mechanism for delivery of redirected data packets to 401 appropriate Content Destinations. This explicitly includes IP 402 checksums and IP TTL, as well as any higher-layer headers -- which 403 SHOULD NOT be altered once captured -- but may not include MAC or 404 lower-layer checksums. 406 DTCP explicitly does not specify the mechanism of data delivery to 407 the Content Destination. Such a delivery mechanism is 408 implementation- specific, and is outside the scope of this document. 410 As an example, Servers could utilize such technologies as VLAN 411 tagging or IP tunneling to deliver entire unaltered data packets to 412 Content Destinations. 414 4. Security Model 416 Since DTCP is, by design, a security protocol, it is imperative that 417 it be resistant to malicious use. 419 4.1. No Information Exposure 421 DTCP was designed with the explicit paradigm that only information 422 intentionally available to a given Control Source is ever exposed to 423 that Control Source. For example: the existence of other Control 424 Sources, or Content Destinations to which it has no access MUST NOT 425 be exposed to a given Control Source, e.g. via notifications or 426 error messages. Also, the server MUST NOT respond to any message 427 that fails its security checks. This basic paradigm MUST be upheld 428 in DTCP Server implementations. 430 4.2. Independence of Control Sources 432 DTCP may be implemented on network elements providing service to 433 different customers. If each customer is allowed access to the DTCP 434 Server, they MUST NOT be aware that another customer is using the 435 DTCP Server. More specifically, neither customer's use (or misuse) 436 of the DTCP Server can affect the other customer's use of it. 438 Limits on service-affecting actions that may be taken by a DTCP 439 Client are outside the scope of this document. 441 4.3. Control Source to Content Destination Access Control 443 A DTCP Server SHOULD provide a mechanism by which each configured 444 Control Source is granted access to one or more Content Destinations. 446 4.4. Per-Message Security Mechanisms 448 The primary motivation behind the per-message security mechanisms is 449 to provide both message integrity as well as source authenticity. 450 Additionally, providing insulation against replay-type attacks is 451 also a motivation, though secondary. 453 DTCP currently provides no mechanism for confidentiality. If 454 confidentiality is required, it is recommended that DTCP messages be 455 sent via a secure transport. 457 Note: Authentication failures, defined as a failure of these per- 458 message security mechanisms, MUST NOT be reported to the DTCP Client. 459 They SHOULD be logged on the DTCP server, and possibly acted upon by 460 administration staff. 462 4.4.1. Sequence Number 463 Every message initiated by a DTCP Client MUST contain a sequence 464 number. The request sequence number is an unsigned 64-bit whole 465 number chosen arbitrarily by the client and maintained by the server 466 persistently for each Control Source. All requests from a given 467 Control Source MUST contain a monotonically-increasing sequence 468 number. The sequence number for each successive request may 469 increment by no more than 256. The stored last-valid sequence number 470 shall only be updated upon receipt of a valid, authentic message. 472 A reply message to a valid request MUST contain the identical 473 sequence number as the associated request. 475 Other than as specified below in "Sequence Number Negative Window", 476 repetition of the last sequence number, or an invalid (non- 477 monotonically-increasing) sequence number, in an otherwise-valid 478 message MUST result in the message being dropped and a security 479 violation being logged, except when the sequence number wraps over 480 zero due to bit-field-length constraints. 482 Rollover of the sequence number shall only be permitted when the MSB 483 of the current sequence number is all-ones; otherwise this shall be 484 considered a security violation. A rollover of the sequence number 485 shall cause both an asynchronous notification message to be sent to 486 any configured static address(es) for the respective Control Source 487 as well as a log message to be generated. 489 It is suggested that clients do whatever possible to persistently 490 store the current sequence number as there is no DTCP method by which 491 to reset the current sequence number. 493 DTCP Servers SHOULD provide some mechanism for manually resetting the 494 sequence number for a given client. 496 Additionally, DTCP Servers SHOULD implement a Negative Window feature 497 as specified in the following section. 499 4.4.1.1. Sequence Number Negative Window 501 Under high load, a multithreaded DTCP client may send multiple 502 requests (with properly incrementing sequence numbers) to the DTCP 503 Server without waiting for each reply to come back individually. 504 Because packets may be reordered through the network, they may arrive 505 at the DTCP Server out of order. 507 For example, the DTCP client may send: 509 1. Request 1 (Seq = 1) 510 2. Request 2 (Seq = 2) 512 3. Request 3 (Seq = 3) 514 But due to network reordering, the DTCP Server may receive: 516 1. Request 1 (Seq = 1) 518 2. Request 3 (Seq = 3) 520 3. Request 2 (INVALID) 522 Unfortunately, the specification of the sequence number above will 523 make Request 2 invalid, because once Request 3 is processed, the 524 stored sequence number in the DTCP Server for that Client has been 525 incremented to 3. 527 Therefore to correct this problem, the DTCP Server SHOULD include a 528 "negative" window as well as the required "positive" window for 529 sequence numbers, and keep track of received sequence numbers within 530 that negative window. However, in order to maintain the replay- 531 protection afforded by the sequence number in the first place, any 532 DTCP Server implementing a negative window MUST also implement 533 tracking of particular sequence numbers received within the union of 534 both windows, and MUST NOT respond to any requests containing a 535 sequence number already received. 537 If the received sequence number is in the negative window, the DTCP 538 Server would simply store that sequence number as seen from that 539 particular DTCP Client and process the packet. If the sequence 540 number of the packet is in the positive window, the new positive and 541 negative window would begin and end at this packet's sequence number 542 respectively with the window sizes remaining the same. So a DTCP 543 packet with sequence number within the negative window but that has 544 not been seen (or anywhere within the positive window) is valid. 546 4.4.2. Hashing Message Authentication Code (HMAC) 548 A DTCP Server MUST store a statically-provisioned secret key for each 549 configured client. This key is manually shared with each DTCP 550 Client. Each request and response message MUST contain, as the last 551 entry, a parameter called Authentication-Info, whose value is the 552 HMAC algorithm specified in [RFC2104] of the rest of the message 553 payload (including the sequence number) generated using a SHA-1 [3] 554 digest and the secret key. This digest is expressed in hexadecimal 555 notation ([0-9a-f]), using 40 UTF-8 [4] characters to express the 556 160-bit SHA-1 hash. 558 Original Message: text 559 Secret Key: K 560 HMAC: hash = SHA1HMAC(K, text) 561 New Message: text + "Authentication-Info: " + hash 563 Figure 2 - Generating the message HMAC from the original message. 565 The shared secret key MUST NOT be sent in any DTCP message. 567 The precise algorithm, excerpted here from RFC-2104 for reference 568 purposes (using SHA-1 as the hashing function H and byte length B=64) 569 is as follows: 571 We define two fixed and different strings ipad and opad as follows 572 (the 'i' and 'o' are mnemonics for inner and outer): 573 ipad = the byte 0x36 repeated B times 574 opad = the byte 0x5C repeated B times. 576 To compute HMAC over the data `text' we perform 577 H(K XOR opad, H(K XOR ipad, text)) 579 5. Application-Layer Message Formats 581 In general, the best source for the message formats is the Formal 582 Syntax specified below. The following prose is provided for 583 informational purposes and implementation guidelines. Where apparent 584 syntactic conflicts exist, the Formal Syntax is defined to be 585 correct. 587 DTCP messages are formatted in human-readable CRLF-delimited UTF-8 588 text format, using a mechanism similar to HTTP [RFC1945] or SIP 589 [RFC3261]. Each message begins with an initial "command" line, 590 followed by an optional series of parameter-value lines. Each token 591 in the command line as well as each option line is separated by one 592 or more white space characters. The entire message MUST end with two 593 CRLFs. 595 The final token in any line MAY have whitespace before its 596 terminating CRLF, but is not so required, and is not so reflected in 597 the ABNF. DTCP servers SHOULD ignore extra whitespace between the 598 final token and the terminating CRLF, but MUST return a Syntax Error 599 otherwise. 601 Parameter names are specified in mixed case, but MUST be matched 602 regardless of case. 604 Control characters or other unprintable characters in the parameter 605 value may be indicated by a backslash (\) followed by precisely three 606 digits indicating the UTF-8 value for the character, possibly 607 including leading zeros. The backslash notation may be used to 608 express any character, including whitespace. Backslash notation is 609 explicitly forbidden from being interpreted as either an inter-token 610 delimiter or an inter-parameter delimiter. 612 DTCP Clients and server MUST NOT rely upon the order of parameters 613 within the DTCP message, since it is not guaranteed (other than the 614 final "Authentication-Info" parameter as noted below). 616 Every DTCP message MUST contain the "Authentication-Info" parameter, 617 and it MUST be the final parameter in the message. Any parameters in 618 any DTCP message following the Authentication-Info parameter MUST be 619 disregarded. 621 If a parameter appears multiple times, the behavior is undefined and 622 not guaranteed; however, if a parameter does show up multiple times, 623 the endpoint SHOULD take the value of the first occurrence and 624 disregard any successive occurrences. 626 5.1. Request General Format 628 Each client-to-server message in DTCP begins with a single request 629 command line with the following format: 631 CRLF 633 The command line is followed by one or more parameter-value pairs, 634 comprising the message body. The message is terminated by two CRLFs. 636 A DTCP request MUST contain the Sequence Number and the Control 637 Source ID parameters. 639 5.2. Response General Format 641 Each server-to-client response message in DTCP shall begin with a 642 single response line with the following format: 644 CRLF 646 where the response-code is a three-digit numeric value, and the 647 response-text is an arbitrary-length text string intended to be 648 human-readable. The response line is followed by one or more 649 parameter-value pairs comprising the message body. The message is 650 terminated by two CRLFs. 652 Responses to successful requests MUST contain the response-code "200" 653 and the response-text "OK". 655 A DTCP response MUST contain the Sequence Number parameter. A DTCP 656 response MUST also contain the Timestamp parameter. 658 5.3. Notification General Format 660 Each server-to-client notification message in the control protocol 661 shall begin with a single response line with the following format: 663 CRLF 665 where the response-code is a three-digit numeric value, and the 666 response-text is an arbitrary-length text string intended to be 667 human-readable. The response line is followed by one or more 668 parameter-value pairs comprising the message body. The message is 669 terminated by two CRLFs. 671 A DTCP notification message MUST contain the Timestamp parameter. 673 5.4. Add Request 675 The Add request specifies a new filter criteria to be merged with the 676 existing tasking list for a given Control Source and Content 677 Destination (regardless of order added). Any missing parameters in 678 the request will inferred to be a wildcard or "don't care". The Add 679 request MAY be accompanied by one or more of the following required 680 filter criterion parameters: 682 1. Source IP address, range or IP + bitmask, or wildcard 684 2. Destination IP address, range, or IP + bitmask, or wildcard 686 3. IP Protocol or range, or wildcard 688 4. Source Layer-4 Port or range, or wildcard (parameter only 689 meaningful when IP protocol range includes protocols 6 or 17) 691 5. Destination Layer-4 Port or range, or wildcard (parameter only 692 meaningful when IP protocol range includes 6 or 17) 694 6. ICMP Type or range, or wildcard (parameter only meaningful when 695 IP protocol range includes protocol 1) 697 7. ICMP Code or range, or wildcard (parameter only meaningful when 698 IP protocol range includes protocol 1) 700 A wildcard in a given field implies that any value will match it 701 (i.e. "don't care"). 703 Additionally, the Add request MUST contain one or more of the 704 following parameters: 706 1. Timeout specified in seconds idle (maximum one day) 708 2. Timeout specified in seconds total (maximum one day) 710 3. Timeout specified in packets (maximum 64 bits) 711 4. Timeout specified in bytes (maximum 64 bits) 713 5. Flag: Static, which indicates that this criterion will never 714 timeout and persist until explicitly deleted. All other timeouts 715 shall be ignored if a STATIC flag is present. 717 Additionally, the Add request may contain one or more of the 718 following parameters: 720 1. Relative Priority (unsigned integer, minimum value 1) (optional, 721 defaults to 1) 723 2. Flag: Send Timeout Async (optional), which will cause the server 724 to send a Asynchronous Notification when the criterion times out 725 for any reason. 727 3. Action (optional), which specifies whether the packet stream 728 identified by the criterion will be a) copied to the Content 729 Destination and also forwarded to its original intended 730 destination ("Copy"), b) copied but not forwarded ("Redirect"), 731 or c) not copied and not forwarded ("Block"). By default, Action 732 is "Copy". 734 Finally, the Add request MUST contain the following control protocol 735 parameters: 737 1. Control Source Identifier 739 2. Content Destination Identifier 741 3. Sequence number (MUST be monotonically increasing for each 742 request from a given Control Source) 744 4. HMAC authenticator (MUST span message payload, plus secret key) 746 Although not explicitly expressed in the request, the DTCP Server 747 MUST maintain the date/time of each filter criterion successfully 748 added. This time is the local DTCP Server time, either maintained 749 independently by the server or synchronized via NTP. 751 5.4.1. Criteria Timeouts 753 Timeouts are required for each filter criterion added. These 754 timeouts may be specified in any of four formats: seconds-idle, 755 seconds-total, bytes, or packets. Any combination of these four 756 timeouts may be used in a filter criterion as long as at least one is 757 used. 759 Once a criterion is added, the timeouts will begin decrementing as 760 appropriate. Only the timeouts that are specified in the request 761 will be used for timing-out that criterion. When any active timeout 762 is decremented to zero, the DTCP Server will automatically delete the 763 filter criterion. For each Control Source, if enabled, when a 764 criterion times-out and is deleted, timeout notifications will be 765 sent to any statically-configured Notification Destination(s) 766 associated with that Control Source. 768 A criterion may be added as STATIC. Any such criterion shall persist 769 in the active state unless and until explicitly deleted or deleted 770 due to congestion, provided the DTCP Server maintains its normal 771 operational state. (See section 5.18 Congestion Notification for 772 more information on congestion and timeouts.) 774 If all timeout values are zero and the criterion is not marked 775 STATIC, the DTCP Server MUST return Error 433 (Improper Timeout 776 Specification) and the criterion must not be added. For STATIC 777 criteria, the DTCP Server MUST ignore the all timeout values. 779 If the server fails, STATIC rules may be lost. Any Control Source 780 that uses STATIC criteria SHOULD attempt to ensure that such criteria 781 are still up and active following any maintenance or failure event on 782 the server. 784 5.5. Add Response 786 The response to a successful Add request will consist of the 787 following parameters: 789 Criteria ID 791 The Criteria ID will be persistent for the duration of that request, 792 until it is removed explicitly by the client, or is removed 793 implicitly by either timeout or some failure of the DTCP Server. The 794 Criteria ID MUST uniquely identify that particular filter criterion 795 for that particular Control Source (and be agnostic to the Content 796 Destination). 798 DTCP Servers MUST ensure that generated Criteria ID are unique for 799 all currently-active requests for a given Control Source. 801 Ideally, the Criteria ID SHOULD be globally unique across Control 802 Sources, but this is not strictly required (since all requests will 803 always be from a particular Control Source). 805 DTCP Servers SHOULD provide unique Criteria IDs for new requests, 806 even if old ones have been deleted resulting in a fragmented ID 807 space. This prevents race conditions that can cause inconsistent 808 behavior e.g., a criterion specified in an Add request gets the same 809 Criterion Id as a recently deleted criterion (deleted due to 810 timeout), and before the delete notification could reach the Control 811 Source, it sends out an explicit delete request for the old 812 criterion, which when received by the DTCP Server would delete the 813 recently added criterion, which is clearly undesirable. 815 This response MUST also include the following parameters: 817 1. Timestamp 819 2. Sequence number (MUST match the sequence number for the request) 821 3. HMAC authenticator (MUST span message payload, plus secret key) 823 Responses to unsuccessful Add requests may take any of the following 824 forms: 826 o Syntax Error 828 o Improper Filter Criterion Specification 830 o Unknown Destination Identifier 832 o Invalid Timeout Specification 834 o Improper Authentication (logged, but never sent to client) 836 o Invalid Sequence Number (logged, but never sent to client) 838 o Unknown Control Source Identifier (logged, but never sent to 839 client) 841 5.6. Delete Request 843 The Delete request removes a particular filter criterion (or 844 optionally all filter criteria) for the particular Control Source. 845 The Delete request MUST take precisely one of the following 846 parameters: 848 o Criteria ID or list of ranges of Criteria IDs 850 o Content Destination Identifier 852 Additionally, the Delete request may contain one or more of the 853 following parameters: 855 o Flag: Static, which indicates that criteria added as STATIC should 856 be deleted as well. (optional) If this flag is omitted, STATIC 857 criteria MUST NOT be deleted. 859 If a single Criteria ID or list of ranges Criteria IDs is specified, 860 the respective criterion/criteria is/are removed from the list of 861 filter conditions that apply for that Control Source. 863 If a Content Destination Identifier is specified, all criteria are 864 removed from the list of filter conditions to that particular Content 865 Destination for that Control Source, except for STATIC criteria 866 --unless the STATIC flag is specified. (Note that any other criteria 867 specified by any other Control Sources MUST remain unaffected.) 869 Additionally, the Delete request MUST contain the following 870 parameters: 872 o Control Source Identifier 874 o Sequence number (MUST be monotonically increasing for each request 875 from a given Control Source) 877 o HMAC authenticator (MUST span message payload, plus secret key) 879 5.7. Delete Response 881 The response to a successful Delete will consist of the following 882 parameter: 884 o Number of Criteria Deleted 886 This parameter is an integer specifying the total number of filter 887 criteria that were actually deleted. The number will be precisely 1 888 if a single, valid Criteria ID is supplied in the Delete request. If 889 multiple valid Criteria IDs are supplied, the number of criteria 890 actually deleted will be returned. 892 If any individual Criteria ID is invalid, the entire response will 893 return an error and no action shall be taken by the server for any 894 supplied Criteria ID. If a Content Destination Identifier is 895 supplied, the number of criteria deleted shall be equal to the total 896 number of active filter criteria from the requesting Control Source 897 to that particular Content Destination. If no such criteria exist, 898 the DTCP Server will return a successful delete response (with 899 criteria deleted parameter set to zero). 901 When a range is specified, any existing criteria matching the 902 Criteria ID in that range (inclusive) will be deleted and the true 903 number of criteria deleted (including possibly zero) will be 904 returned. 906 Trying to delete a STATIC criterion without the STATIC flag in the 907 Delete request will result in that criterion NOT being deleted. Such 908 a deletion attempt will return a success (non-error) response, 909 including the actual number of criteria deleted (which may be zero). 911 This response MUST also include the following parameters: 913 o Timestamp 915 o Sequence number (MUST match the sequence number for the request) 917 o HMAC authenticator (MUST span message payload, plus secret key) 919 Responses to unsuccessful Delete requests may take any of the 920 following forms: 922 o Syntax Error 924 o Unknown Criteria ID 926 o Unknown Destination Identifier 928 o Improper Authentication (logged, but never sent to client) 930 o Invalid Sequence Number (logged, but never sent to client) 932 o Unknown Control Source Identifier (logged, but never sent to 933 client) 935 5.8. Refresh Request 937 The Refresh request updates the timeout for a particular filter 938 criterion or set of filter criteria (or optionally all filter 939 criteria) for the particular Control Source assigned to a particular 940 Content Destination. This is used to maintain active criteria that 941 are in danger of timing-out based on the original Add request. The 942 updated timeout will replace the current remaining timeout, NOT be 943 added to it. The Refresh request MUST take precisely one of the 944 following parameters: 946 o Criteria ID or list of ranges of Criteria IDs 948 o Content Destination Identifier 950 Additionally, the Refresh request MUST contain one or more of the 951 following parameters: 953 o Timeout specified in seconds total 955 o Timeout specified in seconds idle 957 o Timeout specified in packets 959 o Timeout specified in bytes 961 (Note that a Refresh request MUST NOT be used to make an existing 962 filter criterion STATIC. A criterion MUST be added explicitly as 963 STATIC in its original Add.) 965 Finally, the Refresh request MUST contain the following parameters: 967 o Control Source Identifier 969 o Sequence number (MUST be monotonically increasing for each request 970 from a given Control Source) 972 o HMAC authenticator (MUST span message payload, plus secret key) 974 5.9. Refresh Response 976 The response to a successful Refresh will consist of the following 977 parameters: 979 o Number of Criteria Refreshed 981 This parameter is an integer specifying the total number of filter 982 criteria that were actually updated. The number will be precisely 1 983 if a single, valid Criteria ID is supplied. If multiple valid 984 Criteria ID are supplied, the number of criteria updated will be 985 returned, and that will equal the number of supplied Criteria IDs. 986 If any Criteria ID is invalid, the entire response will return an 987 error and no action shall be taken by the server for any supplied 988 Criteria ID. If a Content Destination Identifier is supplied, the 989 number of criteria updated shall be equal to the total number of 990 active filter criteria from the requesting Control Source to that 991 particular Content Destination, including zero (which will NOT return 992 an error). 994 This response MUST also include the following parameters: 996 o Timestamp 998 o Sequence number (MUST match the sequence number for the request) 1000 o HMAC authenticator (MUST span message payload, plus secret key) 1002 Responses to unsuccessful Refresh requests may take any of the 1003 following forms: 1005 o Syntax Error 1007 o Invalid Timeout Specification 1009 o Unknown Criteria ID 1011 o Unknown Destination Identifier 1013 o Improper Authentication (logged, but never sent to client) 1015 o Invalid Sequence Number (logged, but never sent to client) 1017 o Unknown Control Source Identifier (logged, but never sent to 1018 client) 1020 5.10. List Request 1022 The List request makes no change on the DTCP Server, but returns a 1023 list of all criteria that a particular Control Source has added. The 1024 Control Source may request this list on the basis of Content 1025 Destination, Criteria ID, or overall (for that particular Control 1026 Source). The List request takes the following parameters: 1028 o Content Destination Identifier (optional) 1030 o Criteria ID or List of ranges of Criteria IDs (optional) 1032 o Flag: Statistics / Criteria / All 1034 If neither of the optional parameters is included, the server MUST 1035 reply with the full set of criteria associated with that Control 1036 Source. 1038 Additionally, the List request MUST contain the following parameters: 1040 o Control Source Identifier 1042 o Sequence number (MUST be monotonically increasing for each request 1043 from a given Control Source) 1045 o HMAC authenticator (MUST span message payload, plus secret key) 1047 5.11. List Response 1049 The response to a successful List will consist of a formatted list -- 1050 essentially a table -- of filter criteria and related parameters. 1052 Fields will be included and excluded depending on the presence and 1053 the value of Stats/Criteria/All entry in the request as noted in 1054 square brackets [] following the value listed below. Each entry in 1055 the List list shall contain the following fields as specified in the 1056 original criteria: 1058 o Control Source Identifier 1060 o Control Source IP Address 1062 o Content Destination Identifier 1064 o Criteria ID 1066 o Date/Time added 1068 o Specified Source IP address, range or IP + bitmask , or wildcard 1069 [Criteria] 1071 o Specified Destination IP address, range, or IP + bitmask, or 1072 wildcard [Criteria] 1074 o IP Protocol or range, or wildcard [Criteria] 1076 o Source Layer-4 Port or range, or wildcard (parameter only 1077 meaningful when IP protocol range includes protocols 6 or 17) 1078 [Criteria] 1080 o Destination Layer-4 Port or range, or wildcard (parameter only 1081 meaningful when IP protocol range includes 6 or 17) [Criteria] 1083 o ICMP Type or range, or wildcard (parameter only meaningful when IP 1084 protocol range includes protocol 1) [Criteria] 1086 o ICMP Code or range, or wildcard (parameter only meaningful when IP 1087 protocol range includes protocol 1) [Criteria] 1089 o Timeout specified in seconds total [Criteria] 1091 o Timeout specified in seconds idle [Criteria] 1093 o Timeout specified in packets [Criteria] 1095 o Timeout specified in bytes [Criteria] 1097 The List list shall also contain the following statistical 1098 information based on each criterion: 1100 o An ordinal counter to specify the position of this entry in the 1101 context of the list 1103 o An integer specifying the total number of entries in the list 1105 o Timeout remaining in seconds total [Stats] 1107 o Timeout remaining in seconds idle [Stats] 1109 o Timeout remaining in packets [Stats] 1111 o Timeout remaining in bytes [Stats] 1113 o An indication if the timeout is STATIC 1115 o Last 10-second average bandwidth, in bits/second [Stats] 1117 o Total number of packets that have matched this Criteria [Stats] 1119 o Total number of bytes that have matched this Criteria [Stats] 1121 o Total times this rule has been Refreshed [Stats] 1123 o Date/Time of last Refresh [Stats] 1124 This response MUST also include the following parameters: 1126 o Timestamp 1128 o Sequence number (MUST match the sequence number for the request) 1130 o HMAC authenticator (MUST span message payload, plus secret key) 1132 Responses to unsuccessful List requests may take any of the following 1133 forms: 1135 o Syntax Error 1137 o Unknown Destination Identifier 1139 o Unknown Criteria ID 1141 o Improper Authentication (logged, but never sent to client) 1143 o Invalid Sequence Number (logged, but never sent to client) 1145 o Unknown Control Source Identifier (logged, but never sent to 1146 client) 1148 Important Note: the response to the List message, in particular all 1149 entries in the generated table, SHOULD be internally consistent and 1150 atomic, regardless of the activity in progress at the time of and 1151 during the course of transmission of the message. The data SHOULD 1152 represent a snapshot of the relevant information at the quantum in 1153 time that the List message is processed. 1155 5.12. NoOp Request 1157 This request takes no action on the server whatsoever, other than 1158 returning a successful response. The sole purpose of this command is 1159 to verify the end-to-end application-layer connectivity between a 1160 Control Source and the DTCP Server. The NoOp request may contain the 1161 following parameter: 1163 o Flag: SendAsync 1165 See 5.13 NoOp Response for a description of the SendAsync flag. 1167 Additionally, the NoOp request MUST contain the following parameters: 1169 o Control Source Identifier 1171 o Sequence number (MUST be monotonically increasing for each request 1172 from a given Control Source) 1174 o HMAC authenticator (MUST span message payload, plus secret key) 1176 5.13. NoOp Response 1178 The response to a successful NoOp will consist of a successful 1179 response message indicator, and contain the following parameters: 1181 o Timestamp 1183 o Sequence number (MUST match the sequence number for the request) 1185 o HMAC authenticator (MUST span message payload, plus secret key) 1187 If the SendAsync parameter is specified in the NoOp request, the 1188 server shall cause an asynchronous notification message to be sent to 1189 any configured notification destinations for that particular Control 1190 Source. 1192 5.14. Restart Notification 1194 The Restart notification shall be sent from the server to any 1195 configured notification-recipient when the system experiences a 1196 failure such that all the filter criteria are lost. The Restart 1197 notification shall contain the following parameters: 1199 o Restart Reason, a text string indicating the reason for the 1200 restart, if known 1202 o Timestamp 1204 o HMAC authenticator (MUST span message payload, plus secret key) 1206 5.15. Rollover Notification 1208 The Rollover notification shall be sent from the server to any 1209 configured notification-recipient when the server experiences a 1210 sequence-number rollover. The Rollover notification shall contain 1211 the following parameters: 1213 o Timestamp 1215 o HMAC authenticator (MUST span message payload, plus secret key) 1217 5.16. NoOp Notification 1219 The NoOp notification shall be sent from the server to any configured 1220 notification-recipient when the DTCP Server receives a NoOp message 1221 with the SendAsync parameter present. The NoOp notification shall 1222 contain the following parameters: 1224 o Timestamp 1226 o HMAC authenticator (MUST span message payload, plus secret key) 1228 5.17. Timeout Notification 1230 The Timeout notification shall be sent from the server to the 1231 appropriate notification-recipient(s) when the server times out a 1232 filter criterion on any one of its configured timeout parameters and 1233 the criterion contains a SendTimeoutAsync parameter. 1235 The Timeout notification shall contain the following parameters: 1237 o Criteria ID, to indicate the particular criteria that has timed 1238 out 1240 o Timeout specified in seconds total [omit if unconfigured] 1242 o Timeout remaining in seconds total [omit if unconfigured] 1244 o Timeout specified in seconds idle [omit if unconfigured] 1246 o Timeout remaining in seconds idle [omit if unconfigured] 1248 o Timeout specified in packets [omit if unconfigured] 1250 o Timeout remaining in packets [omit if unconfigured] 1252 o Timeout specified in bytes [omit if unconfigured] 1254 o Timeout remaining in bytes [omit if unconfigured] 1256 o Timestamp 1258 o HMAC authenticator (MUST span message payload, plus secret key) 1260 5.18. Congestion Notification 1262 The Congestion notification shall be sent from the server to any 1263 configured notification-recipient when the total 10-second average 1264 data rate (in bits/second) summed over all active filter criteria to 1265 a configured Content Destination exceeds the configured soft limit 1266 for that destination. The Congestion notification shall contain the 1267 following parameters: 1269 o Content Destination ID, to indicate the particular destination 1270 experiencing excessive bandwidth 1272 o Current total 10-second average Bandwidth, in bits/second 1274 o Configured SoftLimit Threshold, in bits/second 1276 o Configured HardLimit Threshold, in bits/second 1277 o Timestamp 1279 o HMAC authenticator (MUST span message payload, plus secret key) 1281 Note that since multiple Control Sources may be responsible for this 1282 overload, this Notification MUST be sent to all configured Control 1283 Sources that have currently-active filter criteria to this particular 1284 Content Destination. 1286 5.19. CongestionDelete Notification 1288 The CongestionDelete notification shall be sent from the server to 1289 any configured notification-recipient when the total 10-second 1290 average data rate (in bits/second) summed over all active filter 1291 criteria to a configured Content Destination exceeds the configured 1292 hard limit for that destination, causing the DTCP Server to begin 1293 purging filter criteria. The CongestionDelete notification shall 1294 contain the following parameters: 1296 o Content Destination ID 1298 o List of Criteria ID purged 1300 o Timestamp 1302 o HMAC authenticator (MUST span message payload, plus secret key) 1304 CongestionDelete messages MUST be specifically and uniquely sent to 1305 all configured notification-recipients for the Control Sources to 1306 which they apply. To be clear: a given Control Source notification- 1307 recipient MUST only receive CongestionDelete messages containing 1308 Criteria ID created by that Control Source. 1310 5.20. DuplicatesDropped Notification 1312 The DuplicatesDropped notification shall be sent from the server to 1313 any configured notification-recipient when capacity has been exceeded 1314 in such a way as to cause packets matching criteria added by the 1315 corresponding Control Source to be dropped. This notification will 1316 be sent periodically as long as packets continue to be dropped. The 1317 DuplicatesDropped notification shall contain the following 1318 parameters: 1320 o Content Destination ID 1322 o Applicable CriteriaID pertaining to Dropped Packets 1324 o Total Number of Dropped Packets 1325 o Sum of Bytes contained in Dropped Packets 1327 o Timestamp 1329 o HMAC authenticator (MUST span message payload, plus secret key) 1331 DuplicatesDropped messages MUST be specifically and uniquely sent to 1332 all configured notification-recipients for the Control Sources to 1333 which they apply. 1335 6. Miscellaneous 1337 6.1. Special treatment of response to List request 1339 The List request inherently provides unique functionality with 1340 respect to the messaging architecture of DTCP. All other requests 1341 result in reasonably terse replies, which can be encapsulated in, at 1342 worst, a few IP packets. 1344 However, the List request will generate an arbitrary amount of reply 1345 data, since it could contain all requests that are still active, up 1346 to the limit of the device. This section specifically describes how 1347 responses to the List request are sent. 1349 a) The full reply to the List request MAY consist of multiple 1350 packets. Each packet will contain a single "Response" element; 1351 therefore, each packet will have a single Status-Line and a single 1352 trailer (Authentication-Info) terminated by 2xCRLF. A UDP packet MUST 1353 NOT contain more than ONE "Response" element. 1355 b) A "Response" element in each packet shall contain zero or more 1356 "List-Resp-Entry" elements (in "List-Resp-Parameters"). Each filter 1357 criteria is encoded into a single "List-Resp-Entry" element. The 1358 sequence number MUST be identical for all "Response" elements in a 1359 multi-packet reply. 1361 c) Each "List-Resp-Entry" element MUST contain the following two 1362 elements: "Criteria-Num" and "Criteria-Count". "Criteria-Num" MUST 1363 be valued as an enumeration starting with 1 (one) and incrementing by 1364 one for each "List-Resp-Entry" sent. "Criteria-Count" SHOULD be set 1365 to the total number of matching Criteria in the given particular LIST 1366 response (see below for potential exceptions). 1368 d) Therefore, a full reply to the List request shall consist of as 1369 many "List-Resp-Entry" elements as necessary to fully transmit the 1370 List, divided into multiple packets as described above. 1372 e) DTCP Servers SHOULD ensure that each "List-Resp-Entry" element is 1373 not divided across multiple IP packets. 1375 f) DTCP Clients can use the simple test (Criteria-Num==Criteria- 1376 Count) to determine if they've received the last packet in the 1377 series. However, in order to ensure that all packets were received 1378 (and, respectively, all List-Resp-Entry elements), the DTCP Client 1379 MUST traverse through the list of Criteria-Count to ensure it's 1380 complete from 1 to XX where XX==Criteria-Num==Criteria-Count. 1382 g) At the UDP layer, all packets in the response MUST contain 1383 identical UDP port numbers. DTCP Clients SHOULD maintain their 1384 socket open until either all expected Response messages are received, 1385 or a timeout occurs. 1387 h) If the List request matches no criteria, but does not supply 1388 invalid Criteria-IDs, the "Response" element will contain zero "List- 1389 Resp-Entry" elements. 1391 i) DTCP Servers MAY simplify their implementation by only including a 1392 single "List-Resp-Entry" element in each "Response" element (and 1393 therefore in each packet). 1395 j) DTCP Servers MAY simplify their implementation by transmitting the 1396 "Criteria-Count" element in each List-Resp-Entry element as ZERO (0) 1397 until the final element is sent, whereupon it is set to the proper 1398 value. 1400 A List response that matches 3 criteria may look as follows: 1402 =============== First UDP packet 1403 DTCP header 1404 Seq: A 1405 criteria-id: x ; this is the first List-Resp-Entry element 1406 ... 1407 criteria-num: 1 1408 criteria-count: 3 1409 criteria-id: y ; this is the second List-Resp-Entry element 1410 ... 1411 criteria-num: 2 1412 criteria-count: 3 1413 HMAC 1414 ================ 1415 =============== Second UDP packet 1416 DTCP header 1417 Seq: A 1418 criteria-id: z ; this is the third List-Resp-Entry element 1419 ... 1420 criteria-num: 3 1421 criteria-count: 3 1422 HMAC 1423 ================ 1425 If the list request matches no criteria, it will look as follows: 1427 =============== First UDP packet 1428 DTCP header 1429 Seq: B 1430 HMAC 1431 ================ 1433 6.2. Error or Exception Conditions 1435 Errors in DTCP requests are reported in response messages via any 1436 Response-Code other than "200" (OK). When such error or exception 1437 condition exists, the server SHOULD attempt to indicate the precise 1438 nature of the error or exception using the Error-Parameters element. 1439 This behavior, though helpful, is not strictly required by the 1440 protocol. 1442 For example, if a Delete request contained a specific Criteria-ID not 1443 currently active in the server, the response error message MUST begin 1444 with a 431 - Unknown Criteria ID response line. The server SHOULD 1445 also add the Criteria-ID parameter indicating the unknown Criteria 1446 ID. 1448 Again, note that authentication failures MUST NOT be reported in 1449 response messages; they MUST be silently dropped. 1451 The DTCP Server MUST attempt to provide the most specific error 1452 message to report the specific error or exception condition. When 1453 the request message meets any of the following conditions, if no such 1454 specific error message exists, the server MAY return a 400 (Bad 1455 Request) error: 1457 o Missing required fields 1459 o Parse failure 1461 o Parameters beyond range 1463 In these cases, the server SHOULD include the specific line from the 1464 request that caused the condition using the Error-Parameters element. 1466 6.3. Extensions in ABNF 1468 Extension placeholders are provided in the formal syntax for the 1469 definition of future methods, parameters, and response-codes. 1470 Vendors SHOULD NOT define implementation-specific extensions; rather, 1471 such extensions SHOULD be brought to the DTCP working group for 1472 inclusion into the protocol, to ensure interoperability. 1474 However, in order to provide faster extensions to the protocol, the 1475 "X-" extension parameter construct has been borrowed from other 1476 protocols, including SIP and SMTP. 1478 The DTCP Server or the DTCP Client MAY include an arbitrary 1479 parameter-value pair, as long as the parameter is preceded by the 1480 character string "X-", and all other parameter-value conventions are 1481 followed. 1483 The sender of such extension parameters MUST NOT rely on the 1484 recipient correctly processing those values. 1486 The recipient of such extension parameters MAY process the values as 1487 appropriate upon receipt, but MUST discard without error those 1488 extension parameters that it does not recognize. 1490 6.4. Current Version 1492 The current version string for this release of the DTCP protocol is: 1494 DTCP/0.7 1496 6.5. No specific port 1498 While it is common practice to register and/or publish a TCP or UDP 1499 port for applications that define them as a layer-4 transport, DTCP 1500 has no specific UDP ports predefined. This is intended both to allow 1501 flexibility for implementers and users, as well as to make it more 1502 difficulty to detect DTCP messages on untrusted networks. 1504 6.6. Unimplemented Protocol Methods and Parameters 1506 Some DTCP Server vendors have indicated their interest in supporting 1507 a subset of the functionality specified here, due to their position 1508 in the security space. Additionally, some constructs (arbitrary 1509 lists, in particular) add complexity to implementations that may not 1510 require that complexity. 1512 To address this need, rather than adding complexity by changing the 1513 grammar to indicate optional sections, specific error messages have 1514 been added to indicate to the client that the server cannot process 1515 the request in its current format. Depending on the request, the 1516 client might be able to reformat that request into one that the 1517 server implementation is able to process. 1519 In order to be compliant with this protocol, the following rules 1520 apply: 1522 a) If a vendor chooses not to implement one or more DTCP Methods, 1523 when responding to a request containing one of the unsupported 1524 methods, the DTCP Server MUST send a "501 Not Implemented" Response 1525 error message, and discontinue processing of that request. 1527 b) If a vendor chooses not to implement a list element, when 1528 responding to a request containing such a list, the DTCP Server MUST 1529 send a "501 Not Implemented" Response error message, and discontinue 1530 processing of that request. 1532 c) If a vendor chooses not to implement one or more specific 1533 parameters or parameter value options in a request, the DTCP Server 1534 MUST send a "501 Not Implemented" Response error message, and 1535 discontinue processing of that request. 1537 d) The DTCP Server SHOULD include the method, parameter, or value 1538 which caused the "501 Not Implemented" error to be sent, within the 1539 error response message (to be consistent with 6.4 above) 1541 e) The DTCP Server SHOULD support prior versions of DTCP. However, if 1542 the vendor chooses not to implement prior versions of the protocol, 1543 the DTCP Server MUST send a "505 DTCP Version not supported" error 1544 message, and discontinue processing of that request. 1546 The onus is on the client to determine if it can reformat the message 1547 to make it acceptable to the particular DTCP Server implementation. 1549 6.7. Version Mismatches 1550 The intent of this section is to clarify any ambiguity arising from 1551 mismatches between DTCP versions supported by the DTCP Client and the 1552 DTCP Server. In practice is has been observed that unintended 1553 consequences have arisen by leaving the implementation vague, so it 1554 was decided that clarifing at least a set of reccomendations, if not 1555 rising to the level of requirements, will help guide DTCP 1556 implementations and help ensure interoperability. 1558 Two possible cases of mismatch exist: when the client exceeds the 1559 server version, and when the server exceeds the client version. They 1560 are handled separately, but the motivation in each case is to permit 1561 maximum compatibility. 1563 In this case, versions are compared numerically, with a single digit 1564 after decimal point. For example: 0.4 is greater than 0.2, 1.9 is 1565 greater than 1.4, and 3.1 is greater than 2.9 1567 6.7.1. DTCP Client version exceeds DTCP Server version 1569 If the DTCP Client attempts to make a request to a DTCP Server using 1570 a DTCP version greater than that supported by the DTCP Server, the 1571 DTCP Server MUST return a "505 DTCP Version not supported" error 1572 message using the GREATEST DTCP version supported by the DTCP Server, 1573 and discontinue processing of that request. It has not way of 1574 knowing what new parameters might exist in a newer version of the 1575 protocol and simply has to abandon processing altogether. 1577 In this case, the onus is on the DTCP Client to revert to an older 1578 version of the protocol specification to talk with this DTCP Server 1579 to ensure that its request is properly handled. 1581 6.7.2. DTCP Server version exceeds DTCP Client version 1583 It is expected that a given DTCP Server will support a range of DTCP 1584 protocol specification versions, for interoperability purposes. 1586 If the DTCP Server receives a request from a DTCP Server using a DTCP 1587 version lesser than the most current version supported by the DTCP 1588 Server, the server SHOULD attempt to process that response using the 1589 semantics of the earlier specification, and MUST reply using the 1590 precise DTCP version included in the request. 1592 If the DTCP server is unable to do this, the DTCP Server MUST return 1593 a "505 DTCP Version not supported" error message using the LEAST DTCP 1594 version supported by the DTCP Server, and discontinue processing of 1595 that request 1597 Asynchronous Notifications sent to a client using an earlier version 1598 are addressed in Section 3.2 (Asynchronous Notifications). 1600 7. Message Payload Examples 1601 Note: These are only examples of message payloads, and are not 1602 intended to illustrate the full breadth of the protocol. Also, 1603 please note that the Authentication-Info shown are correct if each 1604 line is terminated with CRLF as specified and the key "secret" is 1605 used. (Terminating CRLFs are not shown.) 1607 7.1. Successful ADD Request and Response Payload 1609 Following is an example of the UDP payload for an Add request: 1611 ADD DTCP/0.6 1612 Source-Address: 192.168.10.4 1613 Dest-Address: 10.1.1.1-10.1.1.10 1614 Protocol: 6,17 1615 Dest-Port: 53 1616 Timeout-Idle: 600 1617 Action: Copy 1618 Priority: 2 1619 Flags: SendAsync 1620 Cdest-ID: cdst_b 1621 Csource-ID: csrc_a 1622 Seq: 3827443 1623 Authentication-Info: 28eb606458ba46160d7a59da48763020f5aef9f5 1625 Following is the UDP payload of one potential successful response to 1626 that Add request: 1628 DTCP/0.6 200 OK 1629 Criteria-ID: 38224 1630 Seq: 3827443 1631 Timestamp: 2005-01-01 12:01:01.111 1632 Authentication-Info: 38099d03fcb5b12a849b36f9bdccc757303fafd0 1634 7.2. Unsuccessful DELETE Request and Response Payload 1636 Following is an example of the UDP payload for an Delete request: 1638 DELETE DTCP/0.6 1639 Criteria-ID: 55331 1640 Csource-ID: csrc_d 1641 Flags: Static 1642 Seq: 2655371 1643 Authentication-Info: 6af62247a2b59a2a06e0ca08ec5a80a644e2cd67 1645 Following is the UDP payload of one potential unsuccessful response 1646 to that Delete request: 1648 DTCP/0.6 431 Unknown Criteria ID 1649 Criteria-ID: 55331 1650 Seq: 2655371 1651 Timestamp: 2005-02-02 12:02:02.222 1652 Authentication-Info: 5de4552e98832c2d2c3a9ffa8a2958c967b4e1e8 1654 This delete request was unsuccessful because the Criteria ID supplied 1655 did not exist. Note that the error-causing parameter is included 1656 within the reply to assist in debugging. 1658 8. Formal Syntax 1660 All of the mechanisms specified in this document are described in 1661 both prose and an Augmented Backus-Naur Form (ABNF) defined in RFC 1662 4234 [7]. Section 6.1 of RFC 4234 defines a set of core rules that 1663 are used by this specification, and not repeated here. Implementers 1664 need to be familiar with the notation and content of RFC 4234 in 1665 order to understand this specification. Certain basic rules are in 1666 uppercase, such as SP, LWS, HTAB, CRLF, DIGIT, ALPHA, etc. 1668 Note that while much of this syntax is taken from the Session 1669 Initiation Protocol (SIP), some of its constructs have been 1670 simplified for this application here. Where appropriate, these 1671 digressions have been noted with comments. 1673 The following core definitions appear throughout the formal syntax: 1675 COL = *(WSP) ":" *(WSP) ; used in parameter-value pair 1676 NPCHAR = "\" 3DIGIT ; used to express ctrl-chars 1677 DSTRING = *(VCHAR / NPCHAR) ; no embedded whitespace 1678 WC = "*" ; wildcard character for matching 1679 NOT = "!" ; invert character for matching 1680 N64BITNUM = 1*20DIGIT 1681 N32BITNUM = 1*10DIGIT 1682 N16BITNUM = 1*5DIGIT 1683 N8BITNUM = 1*3DIGIT 1684 DAYSEC = 1*5DIGIT 1685 IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT 1686 TEXT = 1*(1*(VCHAR) WSP) ; includes whitespace 1687 DTCP-Time = 4DIGIT "-" 2DIGIT "-" 2DIGIT SP 2DIGIT ":" 1688 2DIGIT ":" 2DIGIT "." 3DIGIT 1689 ; This is ISO date/time: YYYY-MM-DD sp HH:MM:SS.TTT 1691 Additionally, the following definitions are excerpted from RFC 3986 1692 [8]: 1694 IPv6address = 6( h16 ":" ) ls32 1695 / "::" 5( h16 ":" ) ls32 1696 / [ h16 ] "::" 4( h16 ":" ) ls32 1697 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 1698 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 1699 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 1700 / [ *4( h16 ":" ) h16 ] "::" ls32 1701 / [ *5( h16 ":" ) h16 ] "::" h16 1702 / [ *6( h16 ":" ) h16 ] "::" 1704 ls32 = ( h16 ":" h16 ) / IPv4address 1705 ; least-significant 32 bits of address 1707 h16 = 1*4HEXDIG 1708 ; 16 bits of address represented in hexadecimal 1710 Here begins the formal syntax: 1712 DTCP-Message = Request / Response / Notification 1714 Request = Request-Line 1715 ( Add-Req-Parameters 1716 / Delete-Req-Parameters 1717 / Refresh-Req-Parameters 1718 / List-Req-Parameters 1719 / Noop-Req-Parameters) 1720 *(extension-parameter) 1721 Csource-ID 1722 Seq 1723 Authentication-Info 1724 CRLF 1726 Response = Status-Line 1727 ( ( Add-Resp-Parameters 1728 / Delete-Resp-Parameters 1729 / Refresh-Resp-Parameters 1730 / List-Resp-Parameters 1731 / Noop-Resp-Parameters) / Error-Parameters ) 1732 *(extension-parameter) 1733 Timestamp 1734 Seq ; note absence of Csource-ID 1735 Authentication-Info 1736 CRLF 1738 Notification = Status-Line 1739 ( Restart-Notif-Parameters 1740 / Rollover-Notif-Parameters 1741 / Noop-Notif-Parameters 1742 / Timeout-Notif-Parameters 1743 / Congestion-Notif-Parameters 1744 / CongDel-Notif-Parameters ) 1745 *(extension-parameter) 1746 Timestamp 1747 Authentication-Info ; note absence of Seq 1748 CRLF 1750 DTCP-Version = "DTCP" "/" 1*DIGIT "." 1*DIGIT 1752 Status-Line = DTCP-Version SP Status-Code SP Reason-Phrase CRLF 1753 Request-Line = Method SP DTCP-Version CRLF 1755 Method = "ADD" / "DELETE" / "REFRESH" / "LIST" / "NOOP" 1756 / extension-method 1758 extension-method = DSTRING 1760 Status-Code = Provisional 1761 / Success 1762 / Redirection 1763 / Request-Failure 1764 / Server-Failure 1765 / Global-Failure 1766 / extension-code 1768 Reason-Phrase = TEXT ; differs from SIP 1769 extension-code = 3DIGIT 1771 Provisional = "130" ; Sequence Number Rollover (Notif) 1772 / "131" ; NoOp Notification (Notif) 1773 Success = "200" ; OK 1774 Redirection = "390" ; Criterion Timeout Delete (Notif) 1775 Request-Failure = "400" ; Bad Request 1776 / "430" ; Unknown Content Destination 1777 / "431" ; Unknown Criteria ID 1778 / "432" ; Improper Filter Specification 1779 / "433" ; Improper Timeout Specification 1780 / "497" ; Invalid Authentication 1781 ; (never sent to client) 1782 / "498" ; Invalid Sequence Number 1783 ; (never sent to client) 1784 / "499" ; Unknown Control Source Identifier 1785 ; (never sent to client) 1786 Server-Failure = "500" ; Server Internal Error 1787 / "501" ; Not Implemented 1788 / "505" ; DTCP Version not supported 1789 / "550" ; Max Criteria Limit Exceeded 1790 / "551" ; Max Content Destination Exceeded 1791 / "580" ; Congestion (Notif) 1792 / "598" ; Duplicate Packets Dropped (Notif) 1793 / "599" ; Server Restart (Notif) 1794 Global-Failure = "680" ; Criterion Congestion Delete (Notif) 1796 Error-Parameters = Cdest-ID 1797 / Criteria-ID 1798 / Filter-Block 1799 / Timeout-Block 1801 Add-Req-Parameters = Filter-Block Timeout-Block [Action] 1802 Option-Block [Flags] Cdest-ID 1804 Filter-Block = *(Filter-Element) 1805 Timeout-Block = *(Timeout-Element) 1806 TRemaining-Block = *(TRemaining-Element) 1807 Option-Block = *(Option-Element) 1808 Timeout-Required-Block = 1*(Timeout-Element) 1809 TRemaining-Required-Block = 1*(TRemaining-Element) 1811 Filter-Element = Source-Address 1812 / Dest-Address 1813 / Protocol 1814 / Source-Port 1815 / Dest-Port 1816 / ICMP-Type 1817 / ICMP-Code 1819 Timeout-Element = Timeout-Idle 1820 / Timeout-Total 1821 / Timeout-Packets 1822 / Timeout-Bytes 1824 TRemaining-Element = Remaining-Idle 1825 / Remaining-Total 1826 / Remaining-Packets 1827 / Remaining-Bytes 1829 Option-Element = Priority 1831 Add-Resp-Parameters = Criteria-ID 1833 Delete-Req-Parameters = ( (Criteria-ID / Criteria-ID-Filter) 1834 Cdest-ID ) [Flags] 1835 Delete-Resp-Parameters = Criteria-Count 1837 Refresh-Req-Parameters = ( (Criteria-ID / Criteria-ID-Filter) 1838 Cdest-ID ) Timeout-Required-Block 1839 Refresh-Resp-Parameters = Criteria-Count 1841 List-Req-Parameters = [ ( (Criteria-ID / Criteria-ID-Filter) 1842 Cdest-ID ) ] [Flags] 1844 List-Resp-Parameters = *(List-Resp-Entry CRLF) 1846 List-Resp-Entry = Criteria-Count Criteria-Num Main-List 1847 [Criteria-List] [Stats-List] 1849 Main-List = Csource-ID Csource-Address Cdest-ID 1850 Criteria-ID Timestamp 1851 Criteria-List = *(Filter-Element) *(Timeout-Element) [Flags] 1852 Stats-List = TRemaining-Block Stats-Block 1854 Stats-Block = Average-Bandwidth Matching-Packets 1855 Matching-Bytes Num-Refresh Last-Refresh 1857 Noop-Req-Parameters = [Flags] 1858 Noop-Resp-Parameters = [] ; no parameters 1860 Restart-Notif-Parameters = Alert-Info 1861 Rollover-Notif-Parameters = [] ; no parameters 1862 Noop-Notif-Parameters = [] ; no parameters 1863 Timeout-Notif-Parameters = Criteria-ID 1864 / Timeout-Required-Block 1865 / TRemaining-Required-Block 1866 Congestion-Notif-Parameters = Cdest-ID Average-Bandwidth 1867 Alert-Bandwidth Max-Bandwidth 1868 CongDel-Notif-Parameters = Cdest-ID Criteria-ID-Filter 1870 extension-parameter = "X-" DSTRING COL DSTRING CRLF 1871 Csource-ID = "Csource-ID" COL DSTRING CRLF 1872 Seq = "Seq" COL N64BITNUM CRLF 1873 Authentication-Info = "Authentication-Info" COL 40HEXDIG CRLF 1874 ID-List = DSTRING *("," DSTRING) 1875 Cdest-ID = "Cdest-ID" COL ID-List CRLF 1876 Source-Address = "Source-Address" COL IPFilter CRLF 1877 Dest-Address = "Dest-Address" COL IPFilter CRLF 1878 Protocol = "Protocol" COL ProtFilter CRLF 1879 Source-Port = "Source-Port" COL PortFilter CRLF 1880 Dest-Port = "Dest-Port" COL PortFilter CRLF 1881 ICMP-Type = "ICMP-Type" COL ICMPFilter CRLF 1882 ICMP-Code = "ICMP-Code" COL ICMPFilter CRLF 1883 Timeout-Idle = "Timeout-Idle" COL DAYSEC CRLF 1884 Timeout-Total = "Timeout-Total" COL DAYSEC CRLF 1885 Timeout-Packets = "Timeout-Packets" COL N32BITNUM CRLF 1886 Timeout-Bytes = "Timeout-Bytes" COL N64BITNUM CRLF 1887 Priority = "Priority" COL N8BITNUM CRLF 1888 Criteria-ID = "Criteria-ID" COL N32BITNUM CRLF 1889 Criteria-ID-Filter = "Criteria-ID" COL CritFilter CRLF 1890 Criteria-Count = "Criteria-Count" COL N32BITNUM CRLF 1891 Criteria-Num = "Criteria-Num" COL N32BITNUM CRLF 1892 Csource-Address = "Csource-Address" COL (IPv4address / 1893 IPv6address) CRLF 1894 Timestamp = "Timestamp" COL DTCP-Time CRLF 1895 Remaining-Idle = "Remaining-Idle" COL DAYSEC CRLF 1896 Remaining-Total = "Remaining-Total" COL DAYSEC CRLF 1897 Remaining-Packets = "Remaining-Packets" COL N32BITNUM CRLF 1898 Remaining-Bytes = "Remaining-Bytes" COL N64BITNUM CRLF 1899 Average-Bandwidth = "Average-Bandwidth" COL N64BITNUM CRLF 1900 Matching-Packets = "Matching-Packets" COL N64BITNUM CRLF 1901 Matching-Bytes = "Matching-Bytes" COL N64BITNUM CRLF 1902 Num-Refresh = "Num-Refresh" COL N32BITNUM CRLF 1903 Last-Refresh = "Last-Refresh" COL DTCP-Time CRLF 1904 Alert-Info = "Alert-Info" COL TEXT CRLF 1905 Alert-Bandwidth = "Alert-Bandwidth" COL N64BITNUM CRLF 1906 Max-Bandwidth = "Max-Bandwidth" COL N64BITNUM CRLF 1907 Action = "Action" COL ActionEntry CRLF 1909 ActionEntry = "Copy" 1910 / "Block" 1911 / "Redirect" 1912 / extension-action 1914 extension-action = DSTRING 1915 Flags = "Flags" COL FlagEntry *("," FlagEntry) CRLF 1917 FlagEntry = "Static" 1918 / "SendAsync" 1919 / "Stats" 1920 / "Criteria" 1921 / "Both" 1923 IPFilter = [NOT] IPEntry *("," [WSP] [NOT] IPEntry) 1924 ProtFilter = [NOT] ProtEntry *("," [WSP] [NOT] ProtEntry) 1926 PortFilter = [NOT] PortEntry *("," [WSP] [NOT] PortEntry) 1928 ICMPFilter = [NOT] ICMPEntry *("," [WSP] [NOT] ICMPEntry) 1930 CritFilter = [NOT] CritEntry *("," [WSP] [NOT] CritEntry) 1932 IPEntry = IPv4Entry 1933 / IPv6Entry 1935 IPv4Entry = IPv4address ; Single Entry 1936 / IPv4address "/" N8BITNUM ; Address/mask 1937 / IPv4address "-" IPv4address ; Range 1938 / IPv4address "-" WC ; Range to UBOUND 1939 / WC "-" IPv4address ; LBOUND to Range 1940 / WC ; Pure Wildcard 1942 IPv6Entry = IPv6address ; Single Entry 1943 / IPv6address "/" N8BITNUM ; Address/mask 1944 / IPv6address "-" IPv6address ; Range 1945 / IPv6address "-" WC ; Range to UBOUND 1946 / WC "-" IPv6address ; LBOUND to Range 1947 / WC ; Pure Wildcard 1949 PortEntry = N16BITNUM ; Single Entry 1950 / N16BITNUM "-" N16BITNUM ; Range 1951 / N16BITNUM "-" WC ; Range to UBOUND 1952 / WC "-" N16BITNUM ; LBOUND to Range 1953 / WC ; Pure Wildcard 1955 ProtEntry = N8BITNUM ; Single Entry 1956 / N8BITNUM "-" N8BITNUM ; Range 1957 / N8BITNUM "-" WC ; Range to UBOUND 1958 / WC "-" N8BITNUM ; LBOUND to Range 1959 / WC ; Pure Wildcard 1961 ICMPEntry = N8BITNUM ; Single Entry 1962 / N8BITNUM "-" N8BITNUM ; Range 1963 / N8BITNUM "-" WC ; Range to UBOUND 1964 / WC "-" N8BITNUM ; LBOUND to Range 1965 / WC ; Pure Wildcard 1967 CritEntry = N64BITNUM ; Single Entry 1968 / N64BITNUM "-" N64BITNUM ; Range 1969 / N64BITNUM "-" WC ; Range to UBOUND 1970 / WC "-" N64BITNUM ; LBOUND to Range 1971 / WC ; Pure Wildcard 1973 9. Security Considerations 1974 DTCP empowers network security personnel to monitor packet data 1975 transitioning through a network element. As such, it is a powerful 1976 protocol that can cause any network data to be redirected to a 1977 arbitrary location for inspection. Consequently, it is of greatest 1978 criticality that any DTCP Servers fully implement the security model 1979 outlined in this draft. Failure to do so could result in malicious 1980 individuals either obtaining unauthorized access to data or 1981 interruption of data transmission. 1983 10. IANA Considerations 1985 This document has no actions for IANA. 1987 11. Conclusions 1989 This protocol has undergone extensive testing and several rounds of 1990 refinements. The resulting protocol is highly effective at meeting 1991 its goals of providing a real-time mechanism to inspect raw packets 1992 containing security-related events traversing a network in real-time. 1994 12. Acknowledgments 1996 Thanks to all at AT&T and Juniper Networks who provided testing and 1997 support for this experimental protocol 1999 The authors would specifically like to thank Joju Chevookaran, and 2000 Saravanan Deenadayalan from Juniper since they have not only worked 2001 hard on the implementation, but also on the some of the enhancements 2002 (specially VRF support, input/out interface filters etc). 2004 Also, Rick Suntag, Michael Nanashko, and Michael St. Angelo from 2005 AT&T all deserve special note for extensive testing as well as 2006 excellent protocol definition suggestions and corrections. 2008 13. References 2010 [RFC1945] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext 2011 Transfer Protocol -- HTTP/1.0", RFC 1945, DOI 10.17487/ 2012 RFC1945, May 1996, . 2015 [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed- 2016 Hashing for Message Authentication", RFC 2104, DOI 2017 10.17487/RFC2104, February 1997, . 2020 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2021 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 2022 RFC2119, March 1997, . 2025 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2026 A., Peterson, J., Sparks, R., Handley, M. and E. Schooler, 2027 "SIP: Session Initiation Protocol", RFC 3261, DOI 10.17487 2028 /RFC3261, June 2002, . 2031 [RFC5938] Morton, A. and M. Chiba, "Individual Session Control 2032 Feature for the Two-Way Active Measurement Protocol 2033 (TWAMP)", RFC 5938, DOI 10.17487/RFC5938, August 2010, 2034 . 2036 Appendix A. Prior Implementation 2038 This document fully and accurately describes the operation of DTCP/ 2039 0.7 implementations. However, in development of this protocol, some 2040 implementations with working versions of the protocol were released. 2041 This appendix describes the differences between the DTCP/0.7 protocol 2042 specification documented herein and the prior DTCP/0.5 and DTCP/0.6 2043 protocol specifications. 2045 Other than the changes documented in this appendix, the older 2046 protocol specifications precisely follow DTCP/0.7 described herein. 2047 This appendix is provided for backward-compatibility purposes only; 2048 all new implementations should ignore this appendix. 2050 A.1. Version Number 2052 (Modifies section 6.4 Current Version) 2054 o The prior supported version string was exactly: DTCP/0.7 2056 A.2 Response to List Request 2058 (Modifies sections 5.11 List Response, 6.1 Special treatment of 2059 response to List request and 8 Formal Syntax) 2061 The following changes apply only to the elements involved in the 2062 Response message used in reply to the List action. Changes are both 2063 syntactic and semantic in nature. 2065 o The ABNF element called "Criteria-Num" in DTCP/0.7 did not exist 2066 in DTCP/0.5 and was not included in any DTCP message. 2068 o The ABNF element called "Criteria-Count" in DTCP/0.7 was called 2069 "Num-Criteria" in DTCP/0.5. 2071 o The "Num-Criteria" element was only included in the final UDP 2072 packet sent. This signals the end of the List response. 2074 A.3 Changes in response Codes 2076 1. 550: Max Criteria Limit Exceeded 2077 This error message is sent when the number of DTCP ADD requests 2078 received by the server exceeds the allowed limit. Error code 500 2079 used in the earlier Flow-Tap implementations was not clear enough. 2081 2. 551: Max Content Destination Exceeded 2083 Server allows only a certain number of Content Destinations at any 2084 given time, and generates this error message when the server receives 2085 a DTCP ADD request that contains a new content destination after the 2086 number of Content Destinations on that server has already exceeded 2087 the allowable limit. 2089 3. 432: Improper Filter Specification 2091 Generated when an ADD request contains a combination of X-JTap-VRF- 2092 Name, X-JTap-Input-Interface, and X-JTap-Output-Interface fields. 2094 A.4. IP Version 6 2096 The formal ABNF syntax has been updated to include IP Version 6 in 2097 parallel with IP Version 4 both in the filter criteria specification 2098 as well as ancillary addressing information. The intent was to 2099 permit the protocol to operate largely unmodified while allowing the 2100 use of IP Version 6 addressing information. Some implementations may 2101 not support this addressing mode. 2103 A.5. Sequence Number Negative Window 2105 The Negative Window sequence number concept has been added to this 2106 version of DTCP to address empirical errors found when testing with a 2107 high rate of DTCP "ADD" messages over a non-trivial network. 2109 A.6. Version Mismatches 2111 The section on Version Mismatches was added, to account for specific 2112 problems encountered during upgrade of either the client or the 2113 server. In particular, the draft was ambiguous on how the DTCP 2114 Server should behave when servicing clients of various versions. 2116 Appendix B. DTCP Vendor-Specific Extension 2118 B.1.1 Flow-Tap DTCP Extensions 2120 In support of Flow-Tap functionality, the DTCP grammar has been 2121 extended to include new parameters defined below. In general, the 2122 purpose of these parameters is to allow a content destination to be 2123 configured on-demand, rather than pre-configured. General DTCP 2124 grammar does not provide this functionality, so we extend it herein. 2126 Note that "JTap-Failure" below is not a grammar tag; it just defines 2127 a new error value "901' that will be used to indicate any problems 2128 with the X-JTap parameters. 2130 1. X-JTap-Cdest-Dest-Address 2132 IP address(es) of Content destination(s) where the matching packets 2133 need to be sent out. User may specify maximum two IP addresses 2134 separated by a comma. This field MUST be present in the ADD request 2135 otherwise "JTAP-Failure" error will be generated. 2137 2. X-JTap-Cdest-Dest-Port 2139 UDP port number(s) of Content destination(s) where the matching 2140 packets need to be sent out. User may specify maximum two port 2141 numbers separated by a comma. This field MUST be present in the ADD 2142 request otherwise "JTAP-Failure" error will be generated. 2144 3. X-JTap-Cdest-TTL 2146 TTL value to be used in the forwarded packet. This is an optional 2147 field and default of 255 will be used if not specified 2149 4.X-JTap-Cdest-Source-Address 2151 Source IP address from which the forwarded packet needs to besent 2152 from This field MUST be present in the ADD request and "JTap-Failure" 2153 error will be generated if this is not specified 2155 5. X-JTap-Cdest-Source-Port 2157 Source UDP port from which the forwarded packet needs to be sent from 2159 This field MUST be present in the ADD request and "JTap-Failure" 2160 error will be generated if this is not specified. 2162 6. Changes in Cdest-ID 2164 Cdest-ID field enables you to specify more than one content 2165 destination by using a comma separated list. Currently, only two 2166 content destinations are supported. However, note that the number of 2167 entries in all the three fields, Cdest-ID, X-JTap-Cdest-Dest-Address 2168 and X-JTap-Cdest-Dest-Port, must be the same. That is, if you have 2169 only one entry in one of the fields, the other two can have only one 2170 entry each. Error message 432 is generated if the number of entries 2171 in these fields does not match with each other. 2173 7. X-JTap-VRF-Name 2175 OPTIONAL field to specify a VRF name. If it is specified, only the 2176 packets coming to the specified VRF will be monitored. "JTap- 2177 Failure" error will be generated if the VRF is not configured 2179 8. X-JTap-Input-Interface 2180 OPTIONAL field to specify a list of interfaces. If it is specified, 2181 it will be attached to respective input interface(s) instead of 2182 global Flow-Tap filters. This list may contain maximum 8 interfaces 2183 separated by comma. If the unit name of an interface is not 2184 specified, System will assume it as unit 0. "JTap-Failure" error will 2185 be generated if any one of the interfaces in the list is not 2186 configured 2188 9. X-JTap-Output-Interface 2190 OPTIONAL field to specify a list of interfaces. If it is specified, 2191 the filter will be attached to respective output interface(s) instead 2192 of global Flow-Tap filters. This list may contain maximum 8 2193 interfaces separated by comma. If the unit name of an interface is 2194 not specified, System will assume it as unit 0. "JTap-Failure" error 2195 will be generated if any one of the interfaces in the list is not 2196 configured 2198 B.1.2 "Flow-Tap" extension ABNF 2200 IP-4-OR-6 = (IPv4address / IPv6address) 2201 ADDR-LIST = IP-4-OR-6 1*("," IP-4-OR-6) 2202 PORT-LIST = N16BITNUM 1*("," N16BITNUM) 2203 IFL = 3CHAR "-" 2*DIGIT "/" 1*DIGIT "/" 1*DIGIT ["." N16BITNUM] 2204 IFL-LIST8 = IFL 7*("," IFL) 2206 X-JTap-Cdest-Dest-Address = "X-JTap-Cdest-Dest-Address" COL ADDR-LIST 2207 CRLF 2208 X-JTap-Cdest-Dest-Port = "X-JTap-Cdest-Dest-Port" COL PORT-LIST 2209 CRLF 2210 X-JTap-Cdest-TTL = "X-JTap-Cdest-TTL" COL N8BITNUM CRLF 2211 X-JTap-Cdest-Source-Address = "X-JTap-Cdest-Source-Address" COL 2212 (IPv4address / IPv6address) CRLF 2213 X-JTap-Cdest-Source-Port = "X-JTap-Cdest-Source-Port" COL N16BITNUM 2214 CRLF 2215 X-JTap-VRF-Name = "X-JTap-VRF-Name" COL DSTRING 2216 CRLF 2217 X-JTap-Input-Interface = "X-JTap-Input-Interface" COL IFL-LIST8 2218 CRLF 2219 X-JTap-Output-Interface = "X-JTap-Output-Interface" COL IFL-LIST8 2220 CRLF 2222 Authors' Addresses 2224 Sumit Kala 2225 Juniper Networks 2226 Bangalore, Karnataka 560035 2227 INDIA 2229 Phone: +91 8197477794 2230 Email: sumitk@juniper.net 2231 David Cavuto 2232 ATT 2234 Email: cavuto@att.net