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 = *<TEXT-UTF8>
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" <sip:sales@3com.com>
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" <sip:+18475551415@sfour.com>
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]