Internet Engineering Task Force Dean/Belkind/Biggs Internet Draft 3Com draft-dean-phonectl-03.txt January 10, 2001 Expires: July 2001 PhoneControl: A Protocol for Remote Phone Control Status of This Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [1]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as work in progress. The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This document is an individual submission to the IETF. Comments should be directed to the authors. Abstract This document proposes a protocol for remote control of a phone. The extensions proposed are designed to be simple both to understand and to implement. 1 Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [1] and indicate requirement levels for compliant implementations. 2 Definitions Master: A device which issues PhoneControl requests. For example, a personal digital assistant (PDA) or a Personal Computer (PC). Phone: A device which receives control requests and sends responses. For example, a SIP phone or back-to-back UA. Dean/Belkind/Biggs [Page 1] Internet Draft phonectl January 10, 2001 Line: One end of a SIP call leg. Analogous to a line of a multi-line POTS phone. The line connects the phone to another remote SIP endpoint (not to the master). Active: A phone line in a non-idle state. For example: ringing, connected, or indicating failure (fast busy). Back-to-back UA: A device which can connect multiple calls like a user agent would. These calls can then have their media selectively bridged. 3 Introduction This document proposes a protocol for remote control of a phone. The syntax is optimized for a SIP endpoint, and a method of transporting commands over SIP is defined, but non-IP devices can also use it. 4 Message Transport When using a transport layer of SIP, PhoneControl messages shall use the method PHONECTL, but be contained entirely in the body. SIP provides transport, reliability, sequencing, authentication, and addressing. Phonectl message shall have the MIME type text/phonecontrol. 5 PhoneControl Syntax A PhoneControl message consists of a list of RFC822-style headers. Use of line folding is discouraged. Each PhoneControl message begins with a version string. PhoneControl-message = Version-Header *message-header Version-Header = "PhoneControl" ":" PC-Version CRLF PC-Version = "1.0" There are two types of messages, requests and responses. A response is identified by containing a Response header, indicating the result of the action. Only phones send responses. Only masters send requests. 6 Command Header The Command header is a mandatory header for every PHONECTL message. Dean/Belkind/Biggs [Page 2] Internet Draft phonectl January 10, 2001 The command is followed by a case-insensitive string indicating the action to be taken. The command header MUST be copied into the response. Command-Header = "Command" ":" Command-Value Command-Value = "dial" | "hangup" | "digits" | "select" | "lines" | "query" | "login" | "get" | "set" | "capability" | "users" | extension-command extension-command = token 7 Response Header The response header indicates the result of a PhoneControl request. It contains a numeric result code and a response string. Response-Header = "Response" ":" Response-Code SP Response-Value Response-Code = 3DIGIT Response-Value = * 8 Device Header This header is used with select and capability commands. Device names are discovered using the capability command. With the "select" command a phone call can be attached to a device. For example, the following message moves a call to speakerphone: PhoneControl: 1.0 Command: select Line: line3 Device: speakerphone The device header is optional in a select command. When missing a non-hold device will be used. A device may contain the modifier "mute", which disables the local microphone. The devices which prefix with the string mixer tend to be useful for back-to-back UA's. 9 Line Header The phone presents itself as a multi-line phone. Only the phone chooses the line names. The line names MAY contain spaces. The phone SHOULD name the lines with something presentable to the user. The phone may choose to frequently reuse line names, or not. For Dean/Belkind/Biggs [Page 3] Internet Draft phonectl January 10, 2001 example: Line: green Line: 1 Line: 847-555-1415 Line: rick@siphappens.com If the phone uses a SIP URI for the line, it is preferable that the URI is the near-end name of the line. When a PhoneControl command is sent down an established call-leg (one that has had an INVITE), the nickname of "myself" can be used for the line representing call-leg. 10 User Header This header is used by the login command. It is used to identify a user. 11 Access Header This header is used with the capabilities and login command to indicate the access authentication schemes supported by the phone. 12 Authorization Header This header gives credentials to be used by the phone for future requests (not to the master). The format of clear uses digest style parameters. The password is hex encoded. Before the password is hex encoded it is XOR'ed with the MD5 Hash of all passwords used to authenticate the PhoneControl request. The MD5 hash is not hex encoded before XORing. If the password is too long, the hash is repeated. Before XORing the password may be appended with zeros which are discarded upon unencoding. Authorization: clear realm="3com.com",user="Rick",password="17a82cd62e19" 13 Command Header This header is used with the capabilities and login command to indicate the commands supported by the phone. Dean/Belkind/Biggs [Page 4] Internet Draft phonectl January 10, 2001 14 Dial Command The dial command is used to place a call to the address listed in the To header. It is recommended that the command also contain a From header to indicate who initiated the call. For example, to initiate a call the master might send a message that looks like: PhoneControl: 1.0 Command: dial To: "Salesdroid" From: sip: belkind@3com.com The phone responds to the command with a 200 OK it if accepts the request. This does not imply that the INVITE was successful. If accepted, the response MUST contain a Line header indicating to the master on which line the call was made. This identifier can then be used to track the progress of the call. In general, phones must never need to wait on network traffic before responding to a PHONECTL command. Any "to" or "from" header which does not contain a scheme (e.g. sip:) will be mapped to a SIP URI just like the user entered it on the phone interface. e.g. appending a default dialing domain. The dial command may contain Authorization headers to be used on only this call. See the Login Command for more details. 15 Hangup Command The hangup command will cause the phone to terminate a call. If the call is not yet connected, the master MAY include a Status header indicating the status code to return for the incoming INVITE. If no line is given, then the currently selected lines are disconnected. If the master supplies a "To" or "From" header, these MUST match the call leg or the hangup command is rejected. Matching is not strict. A hangup command could look like: PhoneControl: 1.0 Command: hangup Line: Line 2 Hangup command for a locally ringing call: PhoneControl: 1.0 Command: hangup Status: 600 Declined Dean/Belkind/Biggs [Page 5] Internet Draft phonectl January 10, 2001 Line: Line 2 hangup is not appropriate for 300-class responses, use 'redirect' command. 16 Digits Command The digits command is intended for DTMF generation in established calls, but may be used for incremental dialing or other key presses. DTMF digits are enclosed in double quotes. Multiple digits MAY be sent in one request. An additional token of Ok MAY be appended to indicate the end of dialing for those phones which support it. A token of flashhook is also defined: Digits-Header = "Digits" ":" 1*( quoted-string | "ok" | "cancel" | "back" | "flashhook" | extension-button ) An example digits request to dial a number might be: PhoneControl: 1.0 Command: Digits Digits: "5551212" ok Entering DTMF tones during a call can be represented as: PhoneControl: 1.0 Command: Digits Digits: "123" 17 Lines Command The "lines" command allows the master to determine the active lines of a phone. Any non-idle state, such as ringing or call failure (fast busy), is considered to be active. Only the phone chooses the line names. Line names may look like URI's, or descriptions, but SHOULD be human presentable. The line name is used to reference the line in other PhoneControl The body of the response will contain a sequence of headers beginning with a Line header, and followed by zero or more additional headers. Each occurrence of a line header indicates a currently active line. Successive non-line headers describe the state of the previously defined line. Each active line SHOULD return at least the status, to, from, and device headers. Dean/Belkind/Biggs [Page 6] Internet Draft phonectl January 10, 2001 An example "lines" response message might look like: PhoneControl: 1.0 Command: Lines Response: 200 OK Line: red button Status:200 connected To: "Guido Schuster" <5551212@sfour.com> From: Rick@3com.com Device: handset Line: green button Status:200 Ok To: "Ikhlaq Sidhu" <7005554141@sfour.com> From: Rick@3com.com Device: hold Line: blue button Status:401 Authentication Required To: Rick@3com.com From: "Billy Biggs" <911@sfour.com> Device: hold The status header codes are the same status codes defined in RFC2543 Two new (virtual) status codes of are hereby defined... 184 Waiting on DNS 185 Contacting, no response 18 Users Command The master uses this command to determine the users currently logged into a phone. The body of the List Users response contains a sequence of headers beginning with a User header, and followed by zero or more additional headers. Each occurrence of a User header indicates a currently active user. Successive non user headers describe the state of the previously defined user. Each active user SHOULD return at least the status header. The status header codes are the same as the response code to the last register. An example response would be: PhoneControl: 1.0 Command: Users Response: 200 OK User: rick@3com.com Status: 200 OK Dean/Belkind/Biggs [Page 7] Internet Draft phonectl January 10, 2001 User: ronnen@belkind.net Status: 401 Authorization Required 19 Capabilities Command This command is used to discover the features and devices available on the phone. Each phone is responsible for its own devices, and should use names which are human presentable. The first device name MUST correspond to the hold device. An example Capability response could look like: PhoneControl: 1.0 Command: capability Response: 200 Ok Devices: hold handset speaker speakerphone mute Access: basic digest chap Commands: select users login hangup join dial 20 Select Command The select command makes a line off hook. Thus, it will answer a ringing call. The select command MAY contain zero or one device header. (for example hold, handset, speaker, or speakerphone). If device is omitted then a non-hold device will be used. Any previously selected lines for that device are put on hold. To conference, multiple line headers are listed. A line may have only one device, but a device may have multiple lines (e.g. when conferencing). Be aware that the phone may be able to have different lines selected to handset and speakerphone simultaneously. For example, to place the current speakerphone call "Line 1" on hold, and select "Line 2": PhoneControl: 1.0 Command: select Line: Line 2 Device: speakerphone For example, to conference line "1" and "2" on mutted handset: PhoneControl: 1.0 Command: select Device: handset mute Dean/Belkind/Biggs [Page 8] Internet Draft phonectl January 10, 2001 Line: 2 Line: 1 21 Join Command The join command will effect the end of a transfer. The master can either provide two lines (for the end of consultation and supervised transfer), or provide one line and a user header (for blind transfer). In SIP this is usually accomplished a REFER or BYE-Also. 22 Query Command The query command is used to retrieve the _to_, and _from_ of a call- leg and additional stats. The query command MUST include either a Line header indicating the line being queried or a User header. The body of the query response MUST include the near and far names of a call-leg which correspond to the To and From of a SIP message. The phone may include additional information. For example... PhoneControl: 1.0 Command: query Line: line1 PhoneControl: 1.0 Command: query Response: 200 OK Line: line1 To: rick@siphappens.com From: ronnen@siphappens.com Contact: 1415@gw5.3com.com Route: proxy1, proxy2, gw5.3com.com Status: ok Device: handset A query can also specify a user... PhoneControl: 1.0 Command: query User: +18475551415 PhoneControl: 1.0 Command: query Response: 200 OK User: +18475551415@3com.com To: rick@fdd.com From: ronnen@belkind.net Dean/Belkind/Biggs [Page 9] Internet Draft phonectl January 10, 2001 Contact: gw5.3com.com Extra parameters may be included in the response. If a query or users command for a user contains a "Contact:" header it MUST be an unaltered copy from the last REGISTER received. 23 Get Command This command is used to get phone specific parameters. The request body contains a list of parameters, one per RFC822 header of the body. If none are provided, the phone SHOULD volunteer some. The parameters names are not standardized and may change from device to device. The response to a get request will contain a list of headers (name:value) in the body of the message. If the Get request included a parameter that is not supported by the phone, the parameter will not be listed in the response. For example: PhoneControl: 1.0 Command: get Vol: DDD: Nonexistent: The corresponding response: PhoneControl: 1.0 Command: get Response: 200 OK Vol: 5 DDD: 3com.com Suggested parameters are: name description range ------------ ---------------------------- ------------ vol volume [1 - 100] ring-vol ring volume [1 - 100] op outbound proxy SIP-URI ddd default dial domain domain name sidetone sidetone [on off] ring-pitch ring-pitch [400 - 4000] id0 SIP identity of phone SIP-URI pw0 password for phone's identity (encoded) desc description for the phone Dean/Belkind/Biggs [Page 10] Internet Draft phonectl January 10, 2001 speed1 first speeddial SIP-URI speed2 second speeddial SIP-URI vm voicemail listen address SIP-URI aa auto answer [on off] dnd do not disturb [on off] msg message waiting light [on off] fwd 302 forwarding of all calls SIP-URI 24 Set Command This command is used to set a phone specific parameter. The body contains a list of headers (name:value). Any parameter not supported is omitted in the body of the response. The response will contain the modified value of the parameters. For example: PhoneControl: 1.0 Command: set Vol: 9999 DDD: 3com.com Nonexistent: foo The corresponding response: PhoneControl: 1.0 Command: set Response: 200 OK Vol: 100 DDD: 3com.com 25 Login Command The Login command allows the master to login and provide a phone with credentials so the phone has authority to place calls and register (i.e. receive calls). "Login" does not give the master authority to PhoneControl the phone. A phone can regulate PHONECTL access with a 401 Unauthorized response to a PHONECTL request carried via SIP. When this happens the master will reattempt the PHONECTL with an authorization header in the SIP head. The master can set a login duration with an expire header. The master MUST use the expire syntax of seconds from present, but the phone MAY not. An expire of "0" is a logout command. The special expire value of "never" means the login should not expire. Each login command causes the phone to issue a REGISTER request for authentication. Credentials provided with a expired login MAY be Dean/Belkind/Biggs [Page 11] Internet Draft phonectl January 10, 2001 kept until applicable connected calls complete. The login command will be successful (200 OK) even before a REGISTER is sent. Masters wishing to track the progress of this resulting REGISTER message should subscribe or poll with the "users" command. In general, phones must never need to wait on network traffic before responding to a PHONECTL command. Credentials will be sent as Authorization headers. A master MAY choose to provide additional credentials beyond those necessary to login, and the phone will save them for use on future requests such as placing calls. For example... PHONECTL aphone.3com.com SIP/2.0 Via: SIP/2.0/UDP 192.168.1.5 User: rick@sfour.com To: aphone.3com.com From: rick@3com.com Cseq: 1232 PHONECTL Call-ID: 1f9a8c77e6c3d4eb@192.168.1.5 Content-length: 114 PhoneControl: 1.0 Command: Login Access: digest, chap Authorization: clear user="Ronnen",password="38bc993fa3",realm=3com Authorization: clear password="8af7f0b33c",user="Billy",realm="U of Waterloo" Expire: 3600 Call flow for a password request: Master phone far end | | | | Command: Login | | |--------------------->| | | 200 OK | | | User: rick@3com.com | | |<---------------------| REGISTER 3com.com | | |-------------------->| | | 401 | | |<--------------------| | | REGISTER | | | Authorization: | | |-------------------->| | | 200 OK | | |<--------------------| | Command: users | | Dean/Belkind/Biggs [Page 12] Internet Draft phonectl January 10, 2001 |--------------------->| | | User:rick@3com.com | | | Status: 200 OK | | |<---------------------| | | | | Revealing passwords is a security concern. It is not necessary for some modes of operation, but is useful as an alternative to human keying. The login command may contain extra get/set parameters. If possible the phone will use these on a per user basis. 26 SIP SUBSCRIBE/NOTIFY This draft defines a new NOTIFY event of "PhoneControl". A subscriber will receive PHONECTL responses corresponding to timely requests for "lines" and "users". 27 Example Messages * Place a call. PHONECTL aphone.3com.com SIP/2.0 Via: SIP/2.0/UDP To: sip:myphone.3com.com From: sip:mypc.3com.com Cseq: 234234 Call-ID: 098df3j34 Content-Type: text/phonecontrol Content-Length:64 PhoneControl: 1.0 Command: dial To: sip:sales@3com.com From: sip: belkind@3com.com 200 OK SIP/2.0 Via: SIP/2.0/UDP To: sip:myphone.3com.com From: sip:mypc.3com.com Cseq: 234234 PHONECTL Call-ID: 098df3j34 Content-Type: text/phonecontrol Content-Length:112 PhoneControl: 1.0 Command: dial Response: 200 Ok Dean/Belkind/Biggs [Page 13] Internet Draft phonectl January 10, 2001 To: sip:sales@3com.com From: sip: belkind@3com.com Line: Line2 Status: 180 Ringing * Terminate a call. PhoneControl: 1.0 Command: Hangup Line: line4 * Answering a call with handset, speakerphone, etc. PhoneControl: 1.0 Command: Select Line: Line3 Device: handset PhoneControl: 1.0 Command: Select Line: Line3 Device: speakerphone * Conferencing. PhoneControl: 1.0 Command: Select Line: Line3 Line: Line2 Device: speakerphone * Hold PhoneControl: 1.0 Command: Select Line: Line2 Device: hold * Mute a call. PhoneControl: 1.0 Command: Select Line: Line3 Device: handset mute * Subscribe to changes SUBSCRIBE aphone.3com.com SIP/2.0 Via: SIP/2.0/UDP To: sip:myphone.3com.com From: sip:mypc.3com.com Cseq: 234234 Call-ID: 098df3j34 Event: phonecontrol NOTIFY mypc.3com.com SIP/2.0 Dean/Belkind/Biggs [Page 14] Internet Draft phonectl January 10, 2001 Via: SIP/2.0/UDP To: sip:mypc.3com.com From: sip:myphone.3com.com Cseq: 234234 PHONECTL Call-ID: 098df3j34 Content-Type: text/phonecontrol Content-Length:112 PhoneControl: 1.0 Command: lines Response: 200 Ok Line: Line2 To: sip:sales@3com.com From: sip: belkind@3com.com Status: 180 Ringing NOTIFY mypc.3com.com SIP/2.0 Via: SIP/2.0/UDP To: sip:mypc.3com.com From: sip:myphone.3com.com Cseq: 234234 PHONECTL Call-ID: 098df3j34 Content-Type: text/phonecontrol Content-Length:112 PhoneControl: 1.0 Command: users Response: 200 Ok user: "Rick Dean" Status: 200 OK * Blind Transfer an existing call. PhoneControl: 1.0 Command: join Line: Line3 User: +18475551212 * Forward future calls. * Set volume control. PhoneControl: 1.0 Command: Select Line: Line3 Device: handset mute * Login/Logout * Get a list of settable parameters. * Set any or all of the phone parameters. Dean/Belkind/Biggs [Page 15] Internet Draft phonectl January 10, 2001 * Determine the state of the phone. (current calls, call state, active/logged in users, ect_) * Error conditions 28 Security Considerations Although passing passwords in plaintext is terrible security, there are many applications where users already memorize and enter a personal identification number (PIN). This is already plaintext sharing of passwords. Changing these PINs frequently, making them long and different for each service is good practice but presents a significant memorization problem. Storing these passwords on a personal digital assistant (PDA), which delivers them electronically, can improve this. It is assumed that most use of the PHONECTL method will be for physically local devices, as an alternative to human keying. Much of the communication will be over direct device-to-device channels such as infrared. Use of plaintext password over shared medium like Ethernet is discouraged. Phones MAY require different PHONECTL passwords based on the command or line requested, and MAY report incomplete information as security dictates. Previous versions of PHONECTL tried to allow authenticated use without revealing passwords to the phone. The phone would hold requests which needed digest authentication, and the master would assist. This has not worked well in practice. A better solution is one-time and time-sensitive passwords. A PDA with PHONECTL makes this easier. 29 References Handley, M., Schulzrinne, H., Schooler, E., and Rosenberg, J., _SIP: Session Initiation Protocol_, RFC2543, March 1999 Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., Luotonen A., Sink, E., and Stewart, L., _An extension to HTTP: Digest Access Authentication_, RFC2069, January 1997 Crocker, David H., _Standard for the Format of ARPA Internet Text Messages_, RFC822, August 13, 1982 Roach, Adam., _Event Notification in SIP_, draft-roach-sip-subscribe-notify-02.txt, November 2000 More recently updated version of this document can be found at http://phonectl.sfour.com/ Dean/Belkind/Biggs [Page 16] Internet Draft phonectl January 10, 2001 30 Authors' Addresses Rick Dean 3Com 3800 Golf Road Rolling Meadows, IL 60008 Rick_Dean@3com.com sip:Rick_Dean@sip.3com.com Ronnen Belkind 3Com 3800 Golf Road Rolling Meadows, IL 60008 Ronnen_Belkind@3com.com sip:Ronnen_Belkind@sip.3com.com Billy Biggs 3Com 3800 Golf Road Rolling Meadows, IL 60008 Billy_Biggs@3com.com sip:Billy_Biggs@sip.3com.com 31 Full Copyright Statement Copyright (c) The Internet Society (1999). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Dean/Belkind/Biggs [Page 17] Internet Draft phonectl January 10, 2001 Dean/Belkind/Biggs [Page 18]