idnits 2.17.1 draft-bormann-t2trg-slipmux-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 17, 2017) is 2468 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-04 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational T. Kaupat 5 Expires: January 18, 2018 Lobaro UG 6 July 17, 2017 8 Slipmux: Using an UART interface for diagnostics, configuration, and 9 packet transfer 10 draft-bormann-t2trg-slipmux-01 12 Abstract 14 Many research and maker platforms for Internet of Things 15 experimentation offer a serial interface. This is often used for 16 programming, diagnostic output, as well as a crude command interface 17 ("AT interface"). Alternatively, it is often used with SLIP 18 (RFC1055) to transfer IP packets only. 20 The present report describes how to use a single serial interface for 21 diagnostics, configuration commands and state readback, as well as 22 packet transfer. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 18, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Using a UART interface . . . . . . . . . . . . . . . . . . . 3 61 3. Packet Transfer . . . . . . . . . . . . . . . . . . . . . . . 3 62 4. Diagnostics Transfer . . . . . . . . . . . . . . . . . . . . 4 63 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 4 64 6. Framing considerations . . . . . . . . . . . . . . . . . . . 5 65 7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 7.1. Why no shell? . . . . . . . . . . . . . . . . . . . . . . 5 67 7.2. Frame aborts . . . . . . . . . . . . . . . . . . . . . . 6 68 7.3. Unknown initial bytes . . . . . . . . . . . . . . . . . . 6 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 9. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 8 73 10.2. Informative References . . . . . . . . . . . . . . . . . 8 74 Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 8 75 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 78 1. Introduction 80 Many research and maker hardware modules for Internet of Things 81 experimentation ("platforms") offer a serial ("UART") interface. 82 This is often used for programming, diagnostic output, as well as a 83 crude command interface ("AT interface"). Alternatively, it is used 84 with SLIP (RFC1055) to transfer IP packets only; this may require the 85 use of another serial interface for diagnostics and configuration. 87 The present report describes how to use a single serial interface for 88 diagnostics, configuration commands and state readback, as well as 89 packet transfer. 91 1.1. Terminology 93 The term "byte" is used in its now customary sense as a synonym for 94 "octet". Where bit arithmetic is explained, this document uses the 95 notation familiar from the programming language C (including C++14's 96 0bnnn binary literals), except that the operator "**" stands for 97 exponentiation. 99 2. Using a UART interface 101 The serial interfaces provided by today's platforms often do not 102 actually use EIA-232 ("RS-232") levels, but some form of logic levels 103 (TTL or more likely 3.3 V CMOS). The present report does not discuss 104 physical interfacing, but assumes that a TXD (transmit data) pin, a 105 RXD (receive data) pin, and a GND (common ground) pin are all that is 106 available. To interface laptops and similar devices to these serial 107 interfaces, inexpensive ($2) USB to UART adapters based on chips such 108 as PL2303, CP2102 or CH340 are easily obtainable. (The usual care 109 needs to be taken when mixing 3.3 V and 5 V platforms; this is well 110 understood but beyond the scope of the present report.) 112 The general assumption is that a serial port configuration of 8N1 (8 113 bits per character, no parity, 1 stop bit) and a bit rate of 115200 114 bit/s is used. As with the logic levels, alternative arrangements 115 are possible, but a 3.3 V CMOS, 115200 bit/s interface is most likely 116 to provide the best interoperability. 118 While it would be possible to run relatively complex and versatile 119 protocols such as PPP [RFC1661] on such serial interfaces, this goes 120 against a need for simplicity and ease of setup. In today's systems, 121 either weird ad-hoc protocols based on "AT commands" are used that 122 are not interoperable at all, or a simple encapsulation such as SLIP 123 [RFC1055] is used for packet transfer only. 125 For the purposes of the present report, on top of the serial UART 126 protocol, the frame format defined by [RFC1055] is indeed employed. 127 The detailed descriptions below generally describe the frame data 128 before applying SLIP escaping in the transmitter or after removing it 129 in the receiver. 131 The approach described here is informally referred to as "slipmux". 133 3. Packet Transfer 135 Packet transfer uses the definitions of [RFC1055]. However, contrary 136 to the statement in section DEFICIENCIES of [RFC1055], multiplexing 137 is very well possible. A frame used for packet transfer is detected 138 by an initial byte of one of the two forms: 140 o 0x45 to 0x4f: IPv4 packet 142 o 0x60 to 0x6f: IPv6 packet 143 This initial byte forms part of the packet; it is not removed from 144 the payload as with the other formats defined below. 146 There are no changes to the formats defined by [RFC1055], so there 147 should be immediate interoperability with tools such as tunslip. 149 4. Diagnostics Transfer 151 While not transferring a frame bearing a packet, the platform can 152 alternatively transmit a diagnostic frame. These are encoded (and 153 escaped) using SLIP framing exactly like packet frames, but start 154 with the byte 0x0a (ASCII newline) and contain UTF-8 encoded 155 characters after that byte. There is no semantics attached to the 156 diagnostics message, except that it is intended as a human-readable 157 debug or diagnostic message from the platform code. It is generally 158 preferable to end the payload of a diagnostics message in another 159 newline (0x0a, which on the wire is then followed by 0xc0 due to the 160 SLIP framing). Note that, as long as only ASCII characters are used, 161 there is no need to actually perform escaping on the diagnostic 162 message. 164 Since diagnostic messages are intended for humans, they are only 165 defined for the direction from platform to host (e.g., laptop); for 166 robustness when connecting two platform modules, they should be 167 ignored by platform modules. 169 5. Configuration 171 Configuration is performed by sending CoAP messages [RFC7252] in SLIP 172 framing. The encapsulation of a CoAP message starts with an 173 additional byte 0xA9, with the bytes of the CoAP message following 174 (which, as for all data in frames, are escaped as necessary as per 175 [RFC1055]). 177 In contrast to the packet and diagnostics frames defined above, CoAP 178 frames benefit from a frame check mechanism. After the CoAP message, 179 the last two bytes of a CoAP frame therefore contain a 16-bit CRC FCS 180 computed over the byte 0xA9 followed by the (unescaped) bytes of the 181 CoAP message, computed as specified in [RFC1662]. (Note that the two 182 bytes of the CRC are escaped, as necessary, by the SLIP framing, as 183 are all other bytes of the CoAP message.) 185 CoAP messages with incorrect CRCs are silently discarded. 187 Where a local URI needs to be formed for the configuration messages, 188 the URI scheme "coap+uart" is used; the authority part of that URI 189 might be used to refer to local interface names as needed, as in: 191 coap+uart://ttyUSB0/APlist 193 The client could also be using a local mapping table to provide some 194 indirection in translating the authority part to a local identifier 195 of the serial port(e.g., COM0 to ttyUSB0). 197 Using an empty URI authority allows the client to use a default port, 198 as in: 200 coap+uart:///APlist 202 A later version of this report might define some common CoAP 203 resources that research or maker platforms might want to provide, 204 e.g. to cover the configuration and status checking often done by "AT 205 commands" today. 207 6. Framing considerations 209 To make SLIP framing robust, it is important to send SLIP frame 210 delimiters (0xc0) before and after each SLIP frame (maybe unless 211 frames follow each other back to back). This means that empty frames 212 need to be silently ignored by a receiver. 214 If a platform starts to send a packet or message, but then decides it 215 should not complete the message before having sent the rest of the 216 frame, it can send the SLIP ESC (0xdb) followed by SLIP END (0xc0) to 217 abort the frame. Note that this goes beyond the error handling 218 suggested by the section "SLIP DRIVERS" in [RFC1055] and might 219 therefore be of limited interoperability at first. 221 Messages in slipmux are strictly sequential; there is no [RFC2687] 222 style suspension. In particular, this means that diagnostic messages 223 that are generated while another message is in progress may have to 224 be buffered (unless they are important enough to abort the frame as 225 described above). 227 7. Discussion 229 7.1. Why no shell? 231 The present report is somewhat radical in that it does not provide a 232 common staple of interactive computer access: A command line 233 interface (CLI), or "shell". 235 This would be easy to add, but distracts from the use of the platform 236 as a "thing" - it should not have to carry an (even primitive) user 237 interface; instead it should provide what would have been "shell 238 commands" as CoAP resources. 240 As a transition aid, existing shell commands can first be converted 241 to just accept their parameters via CoAP but continue to provide 242 their output as ASCII text over the diagnostic channel. 244 However, in order to aid script-driven use of the platform, the next 245 step should then be to also provide the response to the command in a 246 CoAP response, possibly structured for better use by the script. 247 Often code that was designed to format the data for human consumption 248 can be simplified to just ship the raw data, e.g. in a CBOR data item 249 [RFC7049]. 251 7.2. Frame aborts 253 Implementing frame aborts as described in Section 6 requires a 254 receiver to receive the entire frame before acting on it. For 255 diagnostic information, this is somewhat moot - the information is 256 there independent of whether its frame was aborted or not. For 257 packets, it is usually necessary to check a UDP or TCP header 258 checksum before acting on it, anyway. For CoAP requests, similarly, 259 the CRC needs to be checked. So implementing frame aborts should not 260 be an undue burden. 262 7.3. Unknown initial bytes 264 Frames with unknown initial bytes should be silently ignored. 266 The same is true for frames with initial bytes that are 267 unimplemented. However, there is an expectation that true slipmux 268 implementations do implement CoAP framing. If this is unexpectedly 269 not the case, as a courtesy to a peer CoAP client, a slipmux 270 implementation could at least send CoAP Reset messages: a CoAP frame 271 (initial byte 0xA9) with a message that starts with 0x40 to 0x5f 272 could be replied to with a CoAP frame with a CoAP RST message, 273 containing just these four bytes (as always, escaped as needed, and 274 framed with an initial 0xA9 and a CRC): 276 o 0x70 278 o 0x00 280 o The third (unescaped) byte of the message being replied to 282 o The fourth (unescaped) byte of the message being replied to 284 (Generating proper CoAP framing in response does, require 285 implementing the PPP CRC.) In conjunction with the CoAP ping 286 response of a normal CoAP implementation, this also can be used for 287 liveness testing. 289 (The check for the first byte of the CoAP message is needed to avoid 290 endless back and forth of reset messages in certain error 291 situations.) 293 8. IANA Considerations 295 The present report does not foresee adding additional frame types, 296 but as a matter of precaution, this section might define a registry 297 for initial bytes in a frame. At this point, this would contain: 299 o 0x0a: Diagnostics 301 o 0x45 to 0x4f: IPv4 packet 303 o 0x60 to 0x6f: IPv6 packet 305 o 0xA9: CoAP message with 16-bit FCS 307 If such a registry is desired, the following values for initial bytes 308 should probably be reserved (while all these values could be used if 309 required, implementation is easier if they are not): 311 o 0x00 313 o 0xc0: [RFC1055] END 315 o 0xdb: [RFC1055] ESC 317 There might also be a need to formally register the URI scheme 318 "coap+uart". 320 9. Security Considerations 322 The usual security considerations apply to the IP packets transferred 323 in packet frames. 325 When displaying information from diagnostic frames, care should be 326 taken that features of a terminal triggered e.g. by escape sequences 327 cannot be used for nefarious purposes. 329 The CoAP configuration interface does not itself provide any 330 security. This may be appropriate for the local configuration needs 331 of an experimentation platform that is not expected to be physically 332 connected to any system that is not allowed full control over it 333 (e.g., by using the same physical interface for reflashing new 334 firmware). Where the platform might connect to other systems over 335 serial, object security for CoAP [I-D.ietf-core-object-security] 336 might be employed, or the configuration interface might be restricted 337 to a read-only mode only providing information that does not need 338 confidentiality protection. (It would be possible to provide a DTLS 339 encapsulation, but this might go beyond the objective of extreme 340 simplicity.) 342 10. References 344 10.1. Normative References 346 [RFC1055] Romkey, J., "Nonstandard for transmission of IP datagrams 347 over serial lines: SLIP", STD 47, RFC 1055, 348 DOI 10.17487/RFC1055, June 1988, 349 . 351 [RFC1662] Simpson, W., Ed., "PPP in HDLC-like Framing", STD 51, 352 RFC 1662, DOI 10.17487/RFC1662, July 1994, 353 . 355 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 356 Application Protocol (CoAP)", RFC 7252, 357 DOI 10.17487/RFC7252, June 2014, 358 . 360 10.2. Informative References 362 [I-D.ietf-core-object-security] 363 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 364 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 365 object-security-04 (work in progress), July 2017. 367 [RFC1661] Simpson, W., Ed., "The Point-to-Point Protocol (PPP)", 368 STD 51, RFC 1661, DOI 10.17487/RFC1661, July 1994, 369 . 371 [RFC2687] Bormann, C., "PPP in a Real-time Oriented HDLC-like 372 Framing", RFC 2687, DOI 10.17487/RFC2687, September 1999, 373 . 375 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 376 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 377 October 2013, . 379 Appendix A. Implementation 381 A work in progress implementation of slipmux is available as part of 382 Lobaro's SLIP implementation: 384 https://github.com/Lobaro/slip 385 https://github.com/Lobaro/util-slip 387 Acknowledgements 389 TBD 391 Authors' Addresses 393 Carsten Bormann 394 Universitaet Bremen TZI 395 Postfach 330440 396 Bremen D-28359 397 Germany 399 Phone: +49-421-218-63921 400 Email: cabo@tzi.org 402 Tobias Kaupat 403 Lobaro UG 404 Tempowerkring 21d 405 Hamburg D-21079 406 Germany 408 Phone: +49-40-22816531-0 409 Email: tobias.kaupat@lobaro.de