One document matched: draft-hallambaker-wsconnect-02.xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[
<!ENTITY rfc2629 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml'>
<!ENTITY RFC1035 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1035.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC5280 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC3642 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3642.xml">
<!ENTITY RFC4033 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4033.xml">
<!ENTITY RFC4055 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4055.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC5395 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5395.xml">
<!ENTITY RFC4366 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4366.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY RFC3709 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3709.xml">
<!ENTITY draft-hallambaker-httpsession SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hallambaker-httpsession-01.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-hallambaker-wsconnect-02" ipr="trust200902">
<front>
<title abbrev="JSON Service Connect (JCX) Protocol">JSON Service Connect (JCX) Protocol</title>
<author fullname="Phillip Hallam-Baker" initials="P. M." surname="Hallam-Baker">
<organization>Comodo Group Inc.</organization>
<address>
<email>philliph@comodo.com</email>
</address>
</author>
<date day="13" month="June" year="2013" />
<area>General</area>
<workgroup>Internet Engineering Task Force</workgroup>
<abstract>
<t>
JSON Service Connect (JCX) is a JSON/REST Web Service that may be used to
establish and maintain a 'connection binding' of a device to an account
held with a Web Service Provider. Multiple connection bindings may be
established under the same account to support multiple devices and/or
multiple users of a single device. A connection binding permits a
device to securely connect to one or more services offered by the Web Service
Provider with support for protocol and protocol version agilty and
fault tollerance.
</t>
<t>
The protocol is presented as a HTTP/JSON Web Service and uses the HTTP
session continuation mechanism for
authentication of transaction messages and supports
negotiation of a HTTP session continuation mechanism context for the
established endpoint connections.
</t>
</abstract>
</front>
<middle>
<section title="Definitions">
<section title="Requirements Language">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119" />.
</t>
</section>
</section>
<section title="Introduction and Purpose">
<t>
JSON Service Connect (JCX) is a Web Service that may be used to
establish and maintain a 'connection binding' of a device to an account
held with a Web Service Provider (WSP).
</t>
<t>
JCX is presented in JSON encoding <xref target="RFC4627" /> over a HTTP
Session <xref target="RFC2616" /> using HTTP Session Continuation
<xref target="I-D.hallambaker-httpsession" /> for message layer
authentication and TLS transport for confidentiality and
server authentication.<xref target="RFC4627" />
</t>
<t>
A Connection Binding comprises a set of long term credentials used to
authenticate interactions with the JCX service itself and a set of
'Service Connections' to specific services offered by the Web Service
Provider.
</t>
<t>
Each service connection in turn comprises a collection of 'Instance
Connections' which describe a specific instances of the Web Service.
</t>
<t>
For example Alice is a consumer and example.com a provider of a range
of Web Services including anti-malware protection and management of
home automation devices. Alice has 42 devices of different types that
each make use of one or more of the Web Services proviced by example.com.
All the devices are enrolled in the same JCX account 'alice@example.com'
but each device has a unique connection binding and different devices
make use of different Web Services.
</t>
<t>
The centralized account provides Alice with
a single point of control from which she can authorize the addition of
new devices to the account or the removal of devices that are deactivated.
This allows Alice to avoid the need to manage a device such as a
network-enabled lightswitch through the lightswitch itself.
</t>
<t>
To ensure continuity of service
in case of network failure or administration work, example.com provides
multiple instances of its Web Services hosted on different machines.
Different users MAY be granted access to a different collection of
service instances according to their needs and the service tier they
are subscribed to.
</t>
<section title="Establishing a Web Service Provider Account">
<t>
The means by
which the Web Service Provider Account is established is outside
the scope of this document.
</t>
<t>
In a typical case the user would establish an account with their
chosen Web Service Provider through the normal process of using
a Web Browser to access the Web Service Provider's site and
entering such data as the Web Service Provider requires into
a HTML form.
</t>
<t>
Depending on the circumstances, the data provided by the
applicant may require verification before the account
is created.
</t>
<t>
[Default accounts for appliances that are going to be implicitly authenticated
by reference to the network they are on.]
</t>
</section>
<section title="Establishing a Connection Binding">
<t>
A connection binding represents a long term association
between a device and an account at the Web Service Provider.
The association includes the establishment of an authentication
context between the device and the JCX service.
</t>
<t>
An authentication context consists of:
<list>
<t>
A Context Identifier.
</t>
<t>
An authentication algorithm.
</t>
<t>
A secret key.
</t>
</list>
</t>
<t>
The context identifier is an opaque string assigned by the
JCX service. Following the approach introduced in Kerberos,
a JCX service MAY eliminate the need to store
authentication context information by encoding the authentication
algorithm and encrypted secret key in the context identifier.
</t>
<t>
The authentication context can ensure that
future communications are secured against impersonation if
and only if the original process of establishing a connection
binding was secured against communication. Mutual authentication
is therefore an essential requirement.
</t>
<t>
The means by which the connection binding is established
depend on the affordances of the device in question. Establishing
a connection binding to a device with a keyboard is easily
accomplished through use of a one-time PIN code. But many
embedded devices do not provide a keyboard or similar
affordance.
</t>
<t>
The following modes of session establishement are supported:
<list>
<t>PIN Code Establishement.</t>
<t>Out of Band Completion.</t>
<t>QR Code Establishement.</t>
</list>
</t>
<section title="PIN Code Establishement.">
<t>To establish a connection binding for a new mobile phone, Alice
logs into her JCX account manager and requests a new PIN code.
She then starts the application that makes use of a JCX account
and selects 'create new binding'. She is prompted for and enters
her account name (alice@example.com) and PIN.</t>
<t>
The client connects to the JCX service and verifies that the
TLS certificate presented is correct for example.com and
has been issued in accordance with issue practices that
ensure an appropriately high degree of trust (e.g. the CABForum
Extended Validation requirements).
</t>
</section>
<section title="Out of Band Completion.">
<t>
To establish a connection binding for her new toaster oven,
Alice plugs the appliance into her local network and enters
her account name into the device. Since she has not obtained
a PIN code in advance, she leaves the entry blank.
</t>
<t>
To complete the process, Alice logs into her JCX account where
she sees that a new device is available to add to the account.
To help identify the correct device, there is a picture of the
toaster oven, the model name and serial number.
</t>
</section>
<section title="QR Code Preauthorization.">
<t>
Alice decides to remodel the kitchen completely and plans to install
a dozen new network enabled LED light fixtures. Using an
application on the mobile phone she enabled earlier, Alice
scans a QR code attached to each fixture before the
devices are installed. When the fixtures are installed and powered,
the connection binding is preauthorized.
</t>
</section>
</section>
</section>
<!-- Auto generated examples from JCXExamples.xml -->
<section title="Example Uses" anchor="ConnectionRequestExample">
<section title="PIN code establishment">
<t>
Alice buys a new laptop computer which she wishes to use with
the malware protection service provided by example.com. Alice
has an existing account 'alice' with this Web Service Provider and
obtains a pin code Q80370-1RA606-F04B from the Web Service Provider
Web site.
</t>
<t>
Alice enters the values alice@example.com and
Q80370-1RA606-F04B into the Web Service client she wishes to use
with the Web Service Provider on the new laptop.
</t>
<t>
The client obtains the JCX service for example.com using
DNS SRV discovery. The client establishes a TLS connection to
the service and verifies that the certificate provided has
a valid certificate path, has not been revoked and meets the
validation criteria of the client. Since the purpose of
this particular Web Service client is to provide security, the
client requires that an Extended Validation certificate be
presented.
</t>
<t>
Having established a TLS connection to the JCX Service, the client
sends the following HTTP request:
</t>
<figure>
<artwork>
<![CDATA[Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 470
{
"OpenRequest": {
"Encryption": ["HS256",
"HS384",
"HS512",
"HS256T128"],
"Authentication": ["A128CBC",
"A256CBC",
"A128GCM",
"A256GCM"],
"Account": "alice",
"Domain": "example.com",
"HavePasscode": true,
"HaveDisplay": true,
"Challenge": "d2gdVeQesS3UTOgtK4JSEg==",
"DeviceID": "Serial:0002212",
"DeviceURI": "http://comodo.com/dragon/v3.4",
"DeviceName": "Comodo Dragon"}}]]>
</artwork>
</figure>
<t>
To prevent man in the middle attack, the client does not send the PIN
code in the initial request. The PIN code is only sent after the service
responds with a challenge nonce to be used to prevent replay attack.
</t>
<t>
The service receives the request, determines that is meets its
access control policy and selects a set of cryptographic parameters
from the set proposed by the client. In this case the service prefers
the use of AES128CBC for encryption and the HS256 Message Authentication
Code for authentication.
</t>
<t>
The service determines that a PIN code has been issued for the account and
uses the value of that PIN to generate a response to the challenge
presented by the client. A new challenge is generated to test the
client knowledge of the PIN.
</t>
<t>
[TBS: Is there a need for the service to be able to support multiple
outstanding PIN codes for the same account? This could be supported by
providing the last 2 significant characters of the PIN code to the
service which could use it as an index. This would enable several hundred
simultaneous outstanding requests which should be enough for most applications.
Large volume applications would need to use a different scheme.]
</t>
<t>
The service sends the following response to the client:
</t>
<figure>
<artwork>
<![CDATA[HTTP/1.1 203 Passcode
Content-Type: application/json;charset=UTF-8
Content-Length: 500
{ "Status" : "Authenticate",
"OpenResponse": {
"Status": 203,
"StatusDescription": "Passcode",
"Cryptographic": [{
"Secret": "11bmdFi9Et7KIUg8aeN2AQ==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIO
qPa4oB29dgs/ei6ieINZtmvXNCm2NUkWA=="}],
"Challenge": "alX8aAWH6acSqO3FTT94HA==",
"ChallengeResponse": "enT5myMw8w2hV4H32Ntx/g=="}}]]>
</artwork>
</figure>
<t>
To complete the transaction, the client sends a TicketRequest message
to the service containing a response to the PIN challenge sent by the
service (ChallengeResponse).
</t>
<t>
The TicketRequest message is authenticated using HTTP Session authentication
under the shared secret specified in the OpenResponse message:
</t>
<figure>
<artwork>
<![CDATA[Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 78
Session:
Value=cjkMkfnnYP8JYWZAbRLvtpqImmOK3rsrOT1XcvAgHDk=;
Id=TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIOqPa4
oB29dgs/ei6ieINZtmvXNCm2NUkWA==
{
"TicketRequest": {
"ChallengeResponse": "TctLOG74cwpm26YNpEibcQ=="}}]]>
</artwork>
</figure>
<t>
The service checks the value of ChallengeResponse against the
known PIN and if the result is correct establishes parameters
for the Connection Binding for the device.
</t>
<t>
In this case the server uses the Session Id parameter to
encode permissions associated with the request as described
in [Appendix TBS]. Accordingly the server must replace the
Session Id whenever the associated permissions change.
Accordingly, the server replaces the cryptographic parameters
specified in the OpenResponse request for use in future
JCX service requests.
In this case the server returns three connections, each
offering a
different transport protocol option. Each connection specifies
its
own set of cryptographic parameters (or will when the code is
written
for that).
</t>
<t>
The service also returns a service connection the malware
protection service the client requested access to. This
service connection specifies three different service instances.
Each service instance has its own set of cryptographic
parameters for use with HTTP session authentication.
In this case the three different service instances offer
different means of accessing the same service: as a JSON
Web Service over HTTP, using a binary encoding over a
UDP transport and tunnelling via DNS.
</t>
<figure>
<artwork>
<![CDATA[HTTP/1.1 200 Complete
Content-Type: application/json;charset=UTF-8
Content-Length: 1907
Session:
Value=nKhjR1r2eYPga0rmDfHT4HOvgQ+EuUoQPwzIl0btljs=;
Id=TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIOqPa4
oB29dgs/ei6ieINZtmvXNCm2NUkWA==
{ "Status" : "Success",
"TicketResponse": {
"Status": 200,
"StatusDescription": "Complete",
"Cryptographic": [{
"Protocol": "OBPConnection",
"Secret": "HQuQg4GkzTwTVoGxar0EXg==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"0ulMVMMfY/pLHZ0FlIy2zDnNycYz9Znvs3JJYQGlZ+dWaxMNxm/jLEsJd/
0qsAc5qp8fjBoMN49V9DkDgM4UYJxVriqfr64RyTTgug2taHY="}],
"Service": [{
"Name": "obp1.example.com",
"Port": 443,
"Address": "10.1.2.3",
"Priority": 1,
"Weight": 100,
"Transport": "WebService",
"Cryptographic": {
"Protocol": "OBPQuery",
"Secret": "kezeXxhkzXgxY7vpkHUb1g==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"jpBXvI7/0WTmwI2NN4n7Vvw96nbS9LpSsSNMIkdapiUoLikSkjpgMrtb
VKz5lHOPloCgAyZXxfZpQRsp4oPY4BcRaMw6F5na62IHnBVDeXg="}},
{
"Name": "dns1.example.com",
"Port": 53,
"Address": "10.1.2.2",
"Priority": 1,
"Weight": 100,
"Transport": "DNS",
"Cryptographic": {
"Protocol": "OBPQuery",
"Secret": "Wk3m7DlL/GStBBm3xUjyzg==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"Q9r4hXefHhLvgpKHVg3w2p7VptVH9qidGiIa4Nw3Zp5hZR816h9+PRj5
sye1jmIhy4sYA/jfK/g4OrSngK9xWO7Qg3/iQ+YTAchKQjdJtN4="}},
{
"Name": "udp.example.com",
"Port": 5000,
"Address": "10.1.2.2",
"Priority": 1,
"Weight": 100,
"Transport": "UDP",
"Cryptographic": {
"Protocol": "OBPQuery",
"Secret": "wBiguG9FGj08nS/c/njp4Q==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"F8LPKTL+XaAX0eJsM22fdJ37BRS816dKXD66UbD8NAVKOgOu556uS8WW
AMj+dJbJaErUzo/vw7tY0icCu1bw8qHmOO4gzhbSbD4Nga2EAU4="}}]}
}]]>
</artwork>
</figure>
</section>
<section title="Unbinding">
<t>
After a year of use, Alice decides to replace the laptop with a new one.
Before selling the old laptop on EBay, she tells the Web Service client to
cancel the connection to the Web Service Provider.
</t>
<t>
The client sends the following mesasage to the provider:
</t>
<figure>
<artwork>
<![CDATA[Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 25
Session:
Value=bZU61eCOW4nVnfdJNS719HL4IsNVxtoTgoRt+mqLbWY=;
ID=0ulMVMMfY/pLHZ0FlIy2zDnNycYz9Znvs3JJYQGlZ+dWaxMNxm/jLEsJd/
0qsAc5qp8fjBoMN49V9DkDgM4UYJxVriqfr64RyTTgug2taHY=
{
"UnbindRequest": {}}]]>
</artwork>
</figure>
<t>
The Session ID specifies the connection binding. Since the Unbind Request
is only valid for that connection binding, there is no need to specify the
connection binding further in the request.
</t>
<t>
The server verifies that the request was authenticated and returns a
successful response:
</t>
<figure>
<artwork>
<![CDATA[HTTP/1.1 200 Complete
Content-Type: application/json;charset=UTF-8
Content-Length: 26
Session:
Value=9P1FmroeFU7y9qHgXdSFXH2qSImh0cQpaSgZrx5IswM=;
Id=0ulMVMMfY/pLHZ0FlIy2zDnNycYz9Znvs3JJYQGlZ+dWaxMNxm/jLEsJd/
0qsAc5qp8fjBoMN49V9DkDgM4UYJxVriqfr64RyTTgug2taHY=
{ "Status" : "Success",
"UnbindResponse": {}}]]>
</artwork>
</figure>
<t>
[TBS: Add in the status response back into the JSON message. ]
</t>
</section>
<section title="Out of Band Completion">
<t>
Alice purchases an Internet enabled coffee pot. The installer configures
the coffee pot in her kitchen but does not have access to Alice's JCX
account or a PIN code to configure it.
</t>
<t>
The installer configures the coffee pot to use the JCX account specified
by Alice. The coffee pot does not have a pssscode to enter but does have
a link to an image of the coffee pot.
</t>
<t>
The client sends the following request:
</t>
<t>
[TBS: non pin code example]
</t>
<t>
Since the client does not have a PIN code, there is no need to
return a challenge. Instead the service returns the status "OOB" to
indicate that the transaction will be completed out of band.
</t>
<t>
[TBS: non pin code example]
</t>
<t>
By default the coffee pot attempts to complete the JCX connection at ten second
intervals for the first ten minutes, every thirty seconds for the next
hour, every five minutes for the following 24 hours and once an hour
thereafter.
</t>
<t>
The client sends the following request to check the status of the request:
</t>
<t>
[TBS: should add in a parameter 'don't call again for x seconds']
</t>
<t>
The first service response tells the coffee pot not to ask again until
five minutes have elapsed:
</t>
<t>
[TBS: non pin code example]
</t>
<t>
The installer calls Alice to tell her that the coffee pot is ready to
connect. Alice authorizes the connection remotely via the Web Service
Provider's Web site. Alice identifies the request to connect the
coffee pot by means of the image provided. She can also use the same
image to help determine which connection to cancel when the coffee pot
is replaced.
</t>
<t>
The next time the coffee pot requests a status update, the service
responds with the connection binding parameters:
</t>
<t>
[TBS: non pin code example]
</t>
</section>
</section>
<!-- End section of automatically generated text -->
<section title="OBPConnection">
<section title="Message: Message">
<!-- No parameters -->
</section>
<section title="Message: Response">
<t> <list style="hanging" hangIndent="6">
<t hangText="Status : Integer [0..1] " />
<t>
Application layer server status code
</t>
<t hangText="StatusDescription : String [0..1] " />
<t>
Describes the status code (ignored by processors)
</t>
</list></t>
</section>
<section title="Message: ErrorResponse">
<t>
An error response MAY be returned in response to any request.
</t>
<t>
Note that requests MAY be rejected by the code implementing
the transport binding before application processing begins
and so a server is not guaranteed to provide an error response
message.
</t>
<!-- No parameters -->
</section>
<section title="Message: Request">
<t> <list style="hanging" hangIndent="6">
<t hangText="Ticket : Binary [1..1] " />
<t>
Opaque ticket issued by the server that identifies
the cryptographic parameters for encryption and
authentication of the message payload.
</t>
</list></t>
</section>
<section title="Structure: Cryptographic">
<t>
Parameters describing a cryptographic context.
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Protocol : Label [0..1] " />
<t>
OBP tickets MAY be restricted to use with either the management
protocol (Management) or the query protocol (Query). If so a
service would typically
specify a ticket with a long expiry time or no expiry for use with
the management protocol and a separate ticket for use with the
query protocol.
</t>
<t hangText="Secret : Binary [1..1] " />
<t>
Shared secret
</t>
<t hangText="Encryption : Label [1..1] " />
<t>
Encryption Algorithm selected
</t>
<t hangText="Authentication : Label [1..1] " />
<t>
Authentication Algorithm selected
</t>
<t hangText="Ticket : Binary [1..1] " />
<t>
Opaque ticket issued by the server that identifies
the cryptographic parameters for encryption and
authentication of the message payload.
</t>
<t hangText="Expires : DateTime [0..1] " />
<t>
Date and time at which the context will expire
</t>
</list></t>
</section>
<section title="Structure: ImageLink">
<t> <list style="hanging" hangIndent="6">
<t hangText="Algorithm : Label [0..1] " />
<t>
Image encoding algorithm (e.g. JPG, PNG)
</t>
<t hangText="Image : Binary [0..1] " />
<t>
Image data as specified by algorithm
</t>
</list></t>
</section>
<section title="Structure: Connection">
<t>
Contains information describing a network connection.
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Name : Name [0..1] " />
<t>
DNS Name. Since one of the functions of an OBP service is name
resolution, a DNS name is only used to establish a connection if
connection by means of the IP address fails.
</t>
<t hangText="Port : Integer [0..1] " />
<t>
TCP or UDP port number.
</t>
<t hangText="Address : String [0..1] " />
<t>
IPv4 (32 bit) or IPv6 (128 bit) service address
</t>
<t hangText="Priority : Integer [0..1] " />
<t>
Service priority. Services with lower priority numbers SHOULD
be attempted before those with higher numbers.
</t>
<t hangText="Weight : Integer [0..1] " />
<t>
Weight to be used to select between services of equal priority.
</t>
<t hangText="Transport : Label [0..1] " />
<t>
OBP Transport binding to be used valid values are HTTP, DNS and UDP.
</t>
<t hangText="Expires : DateTime [0..1] " />
<t>
Date and time at which the specified connection context will expire.
</t>
</list></t>
</section>
<section title="Bind">
<t>
Binding a device is a two step protocol that begins with the
Start Query followed by a sequence of Ticket queries.
</t>
</section>
<section title="Message: BindRequest">
<t>
The following parameters MAY occur in either a
StartRequest or TicketRequest:
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Encryption : Label [0..Many] " />
<t>
Encryption Algorithm that the client accepts. A Client MAY
offer multiple algorithms. If no algorithms are specified then
support for the mandatory to implement algorithm is assumed.
Otherwise mandatory to implement algorithms MUST be
specified explicitly.
</t>
<t hangText="Authentication : Label [0..Many] " />
<t>
Authentication Algorithm that the client accepts.
If no algorithms are specified then
support for the mandatory to implement algorithm is assumed.
Otherwise mandatory to implement algorithms MUST be
specified explicitly.
</t>
</list></t>
</section>
<section title="Message: BindResponse">
<t>
The following parameters MAY occur in either a
StartResponse or TicketResponse:
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Cryptographic : Cryptographic [0..Many] " />
<t>
Cryptographic Parameters.
</t>
<t hangText="Service : Connection [0..Many] " />
<t>
A Connection describing an OBP service point
</t>
</list></t>
</section>
<section title="Message: OpenRequest">
<t>
The OpenRequest Message is used to begin a device binding transaction.
Depending on the authentication requirements of the service the
transaction may be completed in a single query or require a
further Ticket Query to complete.
</t>
<t>
If authentication is required, the mechanism to be used depends on
the capabilities of the device, the requirements of the broker and
the existing relationship between the user and the broker.
</t>
<t>
If the device supports some means of data entry, authentication
MAY be achieved by entering a passcode previously delivered out
of band into the device.
</t>
<t>
The OpenRequest specifies the properties of the service
(Account, Domain) and Device (ID, URI, Name) that will remain
constant throughout the period that the device binding is active
and parameters to be used for the mutual authentication protocol.
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Account : String [0..1] " />
<t>
Account name of the user at the OBP service
</t>
<t hangText="Domain : Name [0..1] " />
<t>
Domain name of the OBP broker service
</t>
<t hangText="HavePasscode : Boolean [0..1] Default =False " />
<t>
If 'true', the user has entered a passcode value for
use with passcode authentication.
</t>
<t hangText="HaveDisplay : Boolean [0..1] Default =False " />
<t>
Specifies if the device is capable of displaying information
to the user or not.
</t>
<t hangText="Challenge : Binary [0..1] " />
<t>
Client challenge value to be used in authentication challenge
</t>
<t hangText="DeviceID : URI [0..1] " />
<t>
Device identifier unique for a particular instance of a device such as a MAC or EUI-64 address expressed as a URI
</t>
<t hangText="DeviceURI : URI [0..1] " />
<t>
Device identifier specifying the type of device, e.g. an xPhone.
</t>
<t hangText="DeviceName : String [0..1] " />
<t>
Descriptive name for the device that would distinguish it
from other similar devices, e.g. 'Alice's xPhone".
</t>
</list></t>
</section>
<section title="Message: OpenResponse">
<t>
An Open request MAY be accepted immediately or be held pending
completion of an inband or out-of-band authentication process.
</t>
<t>
The OpenResponse returns a ticket and a set of cryptographic
connection parameters in either case. If the
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="Challenge : Binary [0..1] " />
<t>
Challenge value to be used by the client to respond
to the server authentication challenge.
</t>
<t hangText="ChallengeResponse : Binary [0..1] " />
<t>
Server response to authentication challenge by the client
</t>
<t hangText="VerificationImage : ImageLink [0..Many] " />
<t>
Link to an image to be used in an image verification mechanism.
</t>
</list></t>
</section>
<section title="Message: TicketRequest">
<t>
The TicketRequest message is used to (1) complete a binding request
begun with an OpenRequest and (2) to refresh ticket or connection
parameters as necessary.
</t>
<t> <list style="hanging" hangIndent="6">
<t hangText="ChallengeResponse : Binary [0..1] " />
<t>
The response to a server
authentication challenge.
</t>
</list></t>
</section>
<section title="Message: TicketResponse">
<t>
The TicketResponse message returns cryptographic and/or connection
context information to a client.
</t>
<!-- No parameters -->
</section>
<section title="Unbind">
<t>
Requests that a previous device association be deleted.
</t>
</section>
<section title="Message: UnbindRequest">
<t>
Since the ticket identifies the binding to be deleted, the
only thing that the unbind message need specify is that
the device wishes to cancel the binding.
</t>
<!-- No parameters -->
</section>
<section title="Message: UnbindResponse">
<t>
Reports on the success of the unbinding operation.
</t>
<t>
If the server reports success, the client SHOULD delete the
ticket and all information relating to the binding.
</t>
<t>
A service MAY continue to accept a ticket after an unbind request
has been granted but MUST NOT accept such a ticket for
a bind request.
</t>
<!-- No parameters -->
</section>
</section>
<section title="Mutual Authentication" anchor="MutualAuth">
<t>
A Connection Service MAY require that a connection request be
authenticated. Two authentication mechanisms are defined.
</t>
<t>
<list style="hanging">
<t hangText="">
PIN Code: The client and server demonstrate mutual
knowledge of
a PIN code previously exchanged out of band.
</t>
<t hangText="">
Out of Band Confirmation: The request for access is
confirmed out of band.
</t>
</list>
</t>
<t>
In addition, services MAY accept the use of any message or transport
layer authentication scheme. For example HTTP Session Continuation or
Transport Layer Security with client authentication.
</t>
<section title="PIN Authentication" anchor="ChallengeResponse">
<t>
PIN code authentication provides users with a simple and often familiar
mechanism for authenticating the connection request. The means by which
the user obtains the PIN code is outside the scope of this document.
Possible methods for distributing the PIN code include obtaining the
code from an account management Web site provided by the Web Service
Provider, letter post, email and in person.
</t>
<t>
Although the PIN value is never exposed on the wire in any form,
the protcol considers the PIN value to be text encoded
in UTF8 encoding.
</t>
<t>
To encourage readability, the use of space (0x20) and hyphen (0x2D)
characters to arrange PIN characters into groups of four to seven
characters is encouraged. To avoid the risk of this practice introducing
user error, space and hyphen characters are ignored when processing the PIN
value.
</t>
<t>
Support for the full UNICODE character set in PIN codes is intended
to facilitate provision of PIN codes in the user's native language.
Web Service Providers MAY make use of any UNICODE characters they
choose but capricious choices are likely to cause users difficulty.
For example a PIN code MAY contain the ZAPF Dingbats thick tick mark
(U+2704) but users would almost certainly find it difficult to enter
and may confuse it with the similar thin tick mark (U+2703).
</t>
<t>
Servers that support PIN Authorization SHOULD offer the choice of a
PIN that only uses numeric
digits ('0', '1', '2', '3', '4', '5', '6', '7', '8', '9'). Clients
that support PIN Authorization MUST allow entry of PINS that only
contain numeric digits.
</t>
<t>
The PIN Mechanism is a three step process:
</t>
<t>
<list>
<t>
The client sends an OpenRequest message to the
Service containing a challenge value CC.
</t>
<t>
The service returns an OpenResponse message
containing to the client a server
challenge value SV and a server response value SR.
</t>
<t>
The client sends a TicketRequest message to the
service containing
a client response value CR.
</t>
</list>
</t>
<t>
Since no prior authentication key has been established
the OpenRequest and OpenResponse messages are
sent without message authentication.
</t>
<t>
The Challenge values CC, and SC are cryptographic
nonces. The nonces
SHOULD be generated using an appropriate cryptographic
random
source. The nonces MUST be at least as long as 128
bits, MUST be at least
the minimum key size
of the authentication algorithm used and MUST NOT more
than 640 bits
in length (640 bits should be enough for anybody).
</t>
<t>
The server response and client response values are
generated
using an authentication algorithm selected by the
server from the
choices proposed by the client in the OpenRequest
message.
</t>
<t>
The algorithn chosen may be a MAC algorithm or an
encrypt-with-authentication (EWA) algorithm. If an EWA
is specified,
the encrypted data is discarded and only the
authentication
value is used in its place.
</t>
<t>
Let A(d,k) be the authentication value obtained by
applying the
authentication algorithm with key k to data d.
</t>
<t>
To create the Server Response value, the UTF8 encoding
of the
PIN value 'P' is first pre-processed to remove space and
hyphen characters, then
converted into a symmetric key KPC by using the
Client
challenge value as the key
truncating if necessary and then applied to the
of the
OpenRequest message:
</t>
<figure>
<artwork>
<![CDATA[
KPC = A (PIN, CC)
SR = A (Secret + SC + OpenRequest, KPC)
]]>
</artwork>
</figure>
<t>
In the Web Service Binding, the Payload of the message
is the
HTTP Body as presented on the wire. The Secret and
Server
Challenge are presented in their
binary format and the '+' operator stands for simple
concatenation
of the binary sequences.
</t>
<t>
This protocol construction ensures that the party
constructing
SR:
</t>
<t>
<list>
<t>
Knows the PIN code value (through the construction
of KPC).
</t>
<t>
Is responding to the Open Request Message (SR
depends on
OpenRequest).
</t>
<t>
Has knowlege of the secret key which MUST be used
to
authenticate the following
TicketRequest/TicketResponse
interaction that will establish the actual
connection.
</t>
<t>
Does not provide an oracle the PIN value. That is,
the protocol
does not provide a service that reveals the (since
the value SR
includes the value SC which is a random nonce
generated
by the server and cannot be predicted by the
client).
</t>
</list>
</t>
<t>
To create the Client Response value, secret key is
applied
to the PIN value and server Challenge:
</t>
<figure>
<artwork>
<![CDATA[
CR = A (PIN + SC + OpenRequest, Secret)
]]>
</artwork>
</figure>
<t>
Note that the server can calculate the value of the
Client Response
token at the time that it generates the Server
Challenge.
This minimizes the amount of state that needs to be
carried from
one request to the next in the Ticket value when using
the stateless
server implementation described in section <xref target="stateless" />
</t>
<t>
This protocol construction ensures that the generator
of CR
</t>
<t>
<list>
<t>
Knows the PIN value.
</t>
<t>
Is respoding to the OpenResponse generated by the
server.
</t>
</list>
</t>
<t>
Note that while disclosure of an oracle for the PIN
value is a
concern in the
construction of CR, this is not the case in the
construction of
SR since the client has already demonstrated knowledge
of the
PIN value.
</t>
</section>
<section title="Example: Latin PIN Code">
<t>
The Connection Request example of section
<xref target="ConnectionRequestExample" />
demonstrates the use
of an alphanumeric PIN code using the Latin alphabet.
</t>
<t>
The PIN code is [Q80370-1RA606-F04B] and the authentication algorithm
is [HS256].
The value KP is thus:
</t>
<t>
[TBS]
</t>
<t>
The data over which the hash value is calulated is
Secret + SC + OpenRequest:
</t>
<t>
[TBS]
</t>
<t>
Applying the derrived key to the data produces the
server
response:
</t>
<t>
The data for the client response is PIN + SC:
</t>
<t>
[TBS]
</t>
<t>
Applying the secret key to the data produces the
client
response:
</t>
<t>
[TBS]
</t>
</section>
<section title="Example: Cyrillic PIN Code">
<t>
If the PIN code in the earlier example was [] the
value KP would be:
</t>
<t>
[TBS]
</t>
<t>
The Server Response would be:
</t>
<t>
[TBS]
</t>
<t>
The rest of the protocol would then continue as
before.
</t>
</section>
<section title="Out of Band Confirmation" anchor="OOBConfirmation">
<t>
The Out Of Band Confirmation mechanism is a three step
process in which:
</t>
<t>
<list>
<t>
The client makes an OpenRequest message to the
service
and obtains an OpenResponse message.
</t>
<t>
The connection binding is
authorized through an out of band process.
</t>
<t>
The client makes a TicketRequest to the service
and obtains a TicketResponse message to complete
the exchange.
</t>
</list>
</t>
<t>
Since no prior authentication key has been established
the
OpenRequest and OpenResponse messages are sent without
authentication.
</t>
<t>
The principal concern in the Out Of Band Confirmation
mechanism is ensuring that the party authorizing the
request is able to identify which party originated
the request they are attempting to identify.
</t>
<t>
If a device has the ability to display an image it
MAY set the HasDisplay=true in the OpenRequest message.
If the broker recieves an OpenRequest with the
HasDisplay
value set to true, the OpenResponse MAY contain one or
more
VerificationImage entries specifying image data that
is
to be displayed to the user by both the client and the
confirmation interface.
</t>
<t>
Before confirming the request, the user SHOULD verify
that the two images are the same and reject the request
in the case that they are not.
</t>
<t>
Many devices do not have a display capability, in
particular
an embedded device such as a network switch or a
thermostat.
In this case the device MAY be identified by means of
the
information provided in
DeviceID, DeviceURI, DeviceImage and DeviceName.
</t>
</section>
</section>
<section title="Protocol Binding">
<t>
A single protocol binding is defined:
<list>
<t>JSON encoding is used to express JCX messages.</t>
<t>A HTTP session layer with HTTP session continuation is used for message authentication.</t>
<t>TLS transport is required for confidentiality and service authentication.</t>
</list>
</t>
<t>
Implementations MAY support use of alternative encodings, session layers or transports
provided that the necessary confidentiality and authentication criteria described
below are met. The means by which negotiation of the use of such encodings is achieved
is outside the scop of this document.
</t>
<t>
</t>
<section title="JSON encoding">
<t>
Messages are expressed in JSON encoding <xref target="RFC4627" />.
</t>
</section>
<section title="HTTP Session Layer">
<t>
Messages are presented over a HTTP session layer
<xref target="RFC2616" />.
The use of HTTP as
a session layer permits multiple Web Services on the same host to
share the same DNS name, IP address and port number and enables use
of HTTP Session Continuation <xref target="I-D.hallambaker-httpsession" />
for message authentication.
</t>
<t>
Use of HTTP Session Continuation mechanism allows message authentication
data to be presented in the HTTP message
header rather than the message content provides a clean separation of
the message authentication data from the data being authenticated.
The scope of the authentication data is simply the message content
after transport encoding (e.g. chunked) has been removed.
</t>
<t>
The use of HTTP session continuation is necessary to achieve mutual
authentication even though TLS transport is required.
</t>
<t>
Only the HTTP Session header is used. The negotiation of the Session
parameters is performed within JCX.
</t>
<t>
[TO-DO: Specify TLS binding options?]
</t>
<t>
[TO-DO: Switch back from using JOSE algorithm names to HTTP Session
algorithm names]
</t>
</section>
<section title="TLS transport">
<t>
TLS transport <xref target="RFC4627" /> is used
</t>
<t>
Support for the PKIX logotype extension <xref target="RFC3709" /> is highly recommended
</t>
<t>Use of an enhanced assurance certificate (e.g. CABForum EV) is likely
to be required in most
applications and is strongly recommended if Lotypes are used.
</t>
</section>
</section>
<section title="Service Identification and Discovery">
<t>
The prefix '[PREFIX-TBD]' has been registered for use as a protocol
identifier for JCX in the URI, SRV and Well Known Location registries.
</t>
<t>
The URI form identifying a JCX account identifier is:
</t>
<t>
PREFIX-TBD:<service>:<account>:< or
PREFIX-TBD:<service>:<account>:<:subaccount>
</t>
<t>
Where <service> is the DNS name of the Web Service Provider,
<account> is the name of the account at the service provider and
<subaccount> is an optional sub-account specifier.
</t>
<t>
Use of the URI form is only needed in cases where the purpose of
the identifier is not clear from the context, in a HTML anchor for
example. A JCX client requesting entry of the service account identifier
MUST support entry of the short form identifier:
</t>
<t>
<account>@<service> or
<:subaccount>/<account>@<service>
</t>
<t>
DNS Service (SRV) record discovery is the preferred method of host discovery
as this provides for fault tollerance and load balancing.
</t>
<t>
JCX clients SHOULD support use of DNS SRV records for host discovery and
MUST support use of DNS A/AAAA records for host discovery.
</t>
<t>
A compliant JCX service MUST be offered at the .well-known location
/.well-known/PREFIX-TBD. Use of JCX protocol at other service locations
is permissible for testing and
protocol development purposes but such configurations are not
compliant and clients are not required to support them. The URL for
the JCX service is therefore:
</t>
<t>
https://<service>/.well-known/PREFIX-TBD
</t>
</section>
<section title="Acknowledgements">
<t>
[List of contributors]
</t>
</section>
<section title="Security Considerations">
<section title="Denial of Service">
</section>
<section title="Breach of Trust">
</section>
<section title="Coercion">
</section>
</section>
<section title="IANA Considerations">
<t>
[TBS list out all the code points that require an IANA
registration]
</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC1035;
&RFC2119;
&RFC2616;
&RFC4366;
&RFC4627;
&draft-hallambaker-httpsession;
<reference anchor="X.509">
<front>
<title>
ITU-T Recommendation X.509 (11/2008): Information
technology - Open systems interconnection - The
Directory: Public-key and attribute certificate
frameworks
</title>
<author>
<organization>
International Telecommunication Union
</organization>
</author>
<date month="November" year="2008" />
</front>
<seriesInfo name="ITU-T Recommendation" value="X.509" />
<format type="HTML" target="http://www.itu.int/itu-t/recommendations/rec.aspx?rec=X.509" />
</reference>
<reference anchor="X.680">
<front>
<title>
ITU-T Recommendation X.680 (11/2008): Information
technology - Abstract Syntax Notation One (ASN.1):
Specification of basic notation
</title>
<author>
<organization>
International Telecommunication Union
</organization>
</author>
<date month="November" year="2008" />
</front>
<seriesInfo name="ITU-T Recommendation" value="X.680" />
<format type="HTML" target="http://www.itu.int/itu-t/recommendations/rec.aspx?rec=X.680" />
</reference>
</references>
<references title="Non Normative References">
&RFC3709;
</references>
<section title="Stateless server" anchor="stateless">
<t>
The protocol is designed to permit but not require
the server to store connection binding state in the
Session ID of the HTTP Session Continuation authentication
mechanism.
</t>
<t>
The Session IDs are opaque as far as the client is concerned.
The client receives the Session ID from the service and returns it
with each request. The internal structure of the Session ID is
therefore outside the scope of this specification but is
provided here to assist implementers.
</t>
<t>
In the PIN Authentication example, two SessionIDs are
issued by the server, a temporary ID issued in response
to the initial client OpenRequest and a connection binding
ID issued when the client PIN confirmation is accepted and the
connection binding is created.
</t>
<section title="Temporary ID">
<t>
[TBS]
</t>
</section>
<section title="Connection Binding ID">
<t>
</t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 10:16:49 |