Internet Engineering Task Force P. Hallam-Baker
Internet-Draft Comodo Group Inc.
Intended status: Standards Track January 21, 2014
Expires: July 25, 2014
JSON Service Connect (JCX) Protocol
draft-hallambaker-wsconnect-05
Abstract
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.
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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on July 25, 2014.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
Hallam-Baker Expires July 25, 2014 [Page 1]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Introduction and Purpose . . . . . . . . . . . . . . . . . . 3
2.1. Establishing a Web Service Provider Account . . . . . . . 4
2.2. Establishing a Connection Binding . . . . . . . . . . . . 4
2.2.1. PIN Code Establishement. . . . . . . . . . . . . . . 5
2.2.2. Out of Band Completion. . . . . . . . . . . . . . . . 5
2.2.3. QR Code Preauthorization. . . . . . . . . . . . . . . 6
3. Example Uses . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. PIN code establishment . . . . . . . . . . . . . . . . . 6
3.2. Unbinding . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3. Out of Band Completion . . . . . . . . . . . . . . . . . 11
4. OBPConnection . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1. Message: Message . . . . . . . . . . . . . . . . . . . . 12
4.2. Message: Response . . . . . . . . . . . . . . . . . . . . 12
4.3. Message: ErrorResponse . . . . . . . . . . . . . . . . . 13
4.4. Message: Request . . . . . . . . . . . . . . . . . . . . 13
4.5. Structure: Cryptographic . . . . . . . . . . . . . . . . 13
4.6. Structure: ImageLink . . . . . . . . . . . . . . . . . . 13
4.7. Structure: Connection . . . . . . . . . . . . . . . . . . 14
4.8. Bind . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.9. Message: BindRequest . . . . . . . . . . . . . . . . . . 14
4.10. Message: OpenPINRequest . . . . . . . . . . . . . . . . . 15
4.11. Message: OpenPINResponse . . . . . . . . . . . . . . . . 16
4.12. Message: TicketRequest . . . . . . . . . . . . . . . . . 16
4.13. Message: TicketResponse . . . . . . . . . . . . . . . . . 17
4.14. Unbind . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.15. Message: UnbindRequest . . . . . . . . . . . . . . . . . 17
4.16. Message: UnbindResponse . . . . . . . . . . . . . . . . . 17
5. Mutual Authentication . . . . . . . . . . . . . . . . . . . . 17
5.1. PIN Authentication . . . . . . . . . . . . . . . . . . . 18
5.2. Example: Latin PIN Code . . . . . . . . . . . . . . . . . 20
5.3. Example: Cyrillic PIN Code . . . . . . . . . . . . . . . 21
5.4. Out of Band Confirmation . . . . . . . . . . . . . . . . 21
6. Protocol Binding . . . . . . . . . . . . . . . . . . . . . . 22
6.1. JSON encoding . . . . . . . . . . . . . . . . . . . . . . 22
Hallam-Baker Expires July 25, 2014 [Page 2]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
6.2. HTTP Session Layer . . . . . . . . . . . . . . . . . . . 23
6.3. TLS transport . . . . . . . . . . . . . . . . . . . . . . 23
7. Service Identification and Discovery . . . . . . . . . . . . 24
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 24
9. Security Considerations . . . . . . . . . . . . . . . . . . . 24
9.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 24
9.2. Breach of Trust . . . . . . . . . . . . . . . . . . . . . 25
9.3. Coercion . . . . . . . . . . . . . . . . . . . . . . . . 25
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.1. Normative References . . . . . . . . . . . . . . . . . . 25
11.2. Non Normative References . . . . . . . . . . . . . . . . 26
Appendix A. Stateless server . . . . . . . . . . . . . . . . . . 26
A.1. Temporary ID . . . . . . . . . . . . . . . . . . . . . . 27
A.2. Connection Binding ID . . . . . . . . . . . . . . . . . . 28
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 28
1. Definitions
1.1. Requirements Language
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 [RFC2119].
2. Introduction and Purpose
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).
JCX is presented in JSON encoding [RFC4627] over a HTTP Session
[RFC2616] using HTTP Session Continuation
[I-D.hallambaker-httpsession] for message layer authentication and
TLS transport for confidentiality and server authentication.[RFC4627]
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.
Each service connection in turn comprises a collection of 'Instance
Connections' which describe a specific instances of the Web Service.
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
Hallam-Baker Expires July 25, 2014 [Page 3]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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.
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.
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.
2.1. Establishing a Web Service Provider Account
The means by which the Web Service Provider Account is established is
outside the scope of this document.
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.
Depending on the circumstances, the data provided by the applicant
may require verification before the account is created.
[Default accounts for appliances that are going to be implicitly
authenticated by reference to the network they are on.]
2.2. Establishing a Connection Binding
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.
An authentication context consists of:
A Context Identifier.
An authentication algorithm.
A secret key.
Hallam-Baker Expires July 25, 2014 [Page 4]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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.
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.
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.
The following modes of session establishement are supported:
PIN Code Establishement.
Out of Band Completion.
QR Code Establishement.
2.2.1. PIN Code Establishement.
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.
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).
2.2.2. Out of Band Completion.
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.
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
Hallam-Baker Expires July 25, 2014 [Page 5]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
identify the correct device, there is a picture of the toaster oven,
the model name and serial number.
2.2.3. QR Code Preauthorization.
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.
3. Example Uses
3.1. PIN code establishment
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.
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.
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.
Having established a TLS connection to the JCX Service, the client
sends the following HTTP request:
Hallam-Baker Expires July 25, 2014 [Page 6]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
POST /.well-known/OmniConnect/ HTTP/1.1
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Host: localhost
Content-Length: 310
Expect: 100-continue
Connection: Keep-Alive
{
"OpenPINRequest": {
"Encryption": ["A128CBC",
"A256CBC",
"A128GCM",
"A256GCM"],
"Authentication": ["HS256",
"HS384",
"HS512",
"HS256T128"],
"Account": "alice",
"Domain": "example.com",
"HaveDisplay": false,
"Challenge": "Im7oCgmY9s__-f1nRqYD1g"}}
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.
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.
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.
[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.]
Hallam-Baker Expires July 25, 2014 [Page 7]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
The service sends the following response to the client:
HTTP/1.1 NonAuthoritativeInformation Passcode
Content-Length: 496
Date: Tue, 09 Jul 2013 21:38:18 GMT
Server: Microsoft-HTTPAPI/2.0
{
"OpenPINResponse": {
"Status": 203,
"StatusDescription": "Passcode",
"Challenge": "jxM757OCrWvmRIE48vK7qA",
"ChallengeResponse":
"UTukgyQ0z2BXupMCz_7iVKL2xbJQpUpL0NVJrKrIavY",
"Cryptographic": {
"Secret": "I8MFdHxoaJeBhf5byd-Xjg",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"SWUpyRVzEjGFw3kzrVVjoSFxY5fakzj8v8O2nNQttqcIn_XoDiIjX2GZX_
NUcxMERe64Ahg-TtQ-xsWO5a03MlndS62k9AhbfIN1EQR6X14UvFKZbkNcB
Oe09YQT5gXgOpfPXBKvUrw70M0U78U7kQ"}}}
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).
The TicketRequest message is authenticated using HTTP Session
authentication under the shared secret specified in the OpenResponse
message:
POST /.well-known/OmniConnect/ HTTP/1.1
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Session: Value=8PfyBK0fmUQiRgozFTVZaoGFK2SWrYurcdPjSZHtcYY;
Id=SWUpyRVzEjGFw3kzrVVjoSFxY5fakzj8v8O2nNQttqcIn_XoDiIjX2GZX_NU
cxMERe64Ahg-TtQ-xsWO5a03MlndS62k9AhbfIN1EQR6X14UvFKZbkNcBOe09YQ
T5gXgOpfPXBKvUrw70M0U78U7kQ
Host: localhost
Content-Length: 95
Expect: 100-continue
{
"TicketRequest": {
"ChallengeResponse":
"FlYXTKEOwD8uobvkjUu0GgjQBtfLfCSsEH8EHgfPO4g"}}
Hallam-Baker Expires July 25, 2014 [Page 8]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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.
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).
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.
Hallam-Baker Expires July 25, 2014 [Page 9]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
HTTP/1.1 OK Complete
Content-Length: 813
Date: Tue, 09 Jul 2013 21:38:18 GMT
Server: Microsoft-HTTPAPI/2.0
{
"TicketResponse": {
"Status": 200,
"StatusDescription": "Complete",
"Cryptographic": [{
"Protocol": "OBPConnection",
"Secret": "zfgDHAp140WB2JjsW-PU_g",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"d2QBEuI85Vt2aCw1EIcAwRuzCAO7Qctu_ZlcjQ6nGcbu2s-x0L3f1dM1
xoSppEFclHiRQAPhsVPjSap9bCuDnKVVAfi33xGihFEcrbqho1k"}],
"Service": [{
"Port": 0,
"Priority": 0,
"Weight": 0,
"Transport": "WebService",
"Cryptographic": {
"Protocol": "OBPQuery",
"Secret": "KLyB4BT43SShFPw8B1_K2Q",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"Jg3BJ086IutOvyLpYAbJZg7CHg2s7MoL81sRM15RUI7Tk0U2Hh9j7U
pjdGIjhcqVodbik_kq1zOK1nXqgBcfSxZRE9wJyTDr3ll6Yf7A_Pk"}
}]}}
3.2. Unbinding
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.
The client sends the following mesasage to the provider:
Hallam-Baker Expires July 25, 2014 [Page 10]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
POST /.well-known/OmniConnect/ HTTP/1.1
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Session: Value=TThHGCV_-9THKabQIM1bfcKLoEStiRV9bJZIXxm8qx0;
Id=SWUpyRVzEjGFw3kzrVVjoSFxY5fakzj8v8O2nNQttqcIn_XoDiIjX2GZX_NU
cxMERe64Ahg-TtQ-xsWO5a03MlndS62k9AhbfIN1EQR6X14UvFKZbkNcBOe09YQ
T5gXgOpfPXBKvUrw70M0U78U7kQ
Host: localhost
Content-Length: 24
Expect: 100-continue
{
"UnbindRequest": {}}
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.
The server verifies that the request was authenticated and returns a
successful response:
HTTP/1.1 OK Unbound
Content-Length: 79
Date: Tue, 09 Jul 2013 21:38:18 GMT
Server: Microsoft-HTTPAPI/2.0
{
"UnbindResponse": {
"Status": 200,
"StatusDescription": "Unbound"}}
[TBS: Add in the status response back into the JSON message. ]
3.3. Out of Band Completion
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.
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.
The client sends the following request:
[TBS: non pin code example]
Hallam-Baker Expires July 25, 2014 [Page 11]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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.
[TBS: non pin code example]
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.
The client sends the following request to check the status of the
request:
[TBS: should add in a parameter 'don't call again for x seconds']
The first service response tells the coffee pot not to ask again
until five minutes have elapsed:
[TBS: non pin code example]
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.
The next time the coffee pot requests a status update, the service
responds with the connection binding parameters:
[TBS: non pin code example]
4. OBPConnection
4.1. Message: Message
4.2. Message: Response
Status : Integer [0..1]
Application layer server status code
StatusDescription : String [0..1]
Describes the status code (ignored by processors)
Hallam-Baker Expires July 25, 2014 [Page 12]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
4.3. Message: ErrorResponse
An error response MAY be returned in response to any request.
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.
4.4. Message: Request
4.5. Structure: Cryptographic
Parameters describing a cryptographic context.
Protocol : Label [0..1]
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.
Secret : Binary [1..1]
Shared secret
Encryption : Label [1..1]
Encryption Algorithm selected
Authentication : Label [1..1]
Authentication Algorithm selected
Ticket : Binary [1..1]
Opaque ticket issued by the server that identifies the
cryptographic parameters for encryption and authentication of
the message payload.
Expires : DateTime [0..1]
Date and time at which the context will expire
4.6. Structure: ImageLink
Algorithm : Label [0..1]
Image encoding algorithm (e.g. JPG, PNG)
Image : Binary [0..1]
Image data as specified by algorithm
Hallam-Baker Expires July 25, 2014 [Page 13]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
4.7. Structure: Connection
Contains information describing a network connection.
Name : Name [0..1]
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.
Port : Integer [0..1]
TCP or UDP port number.
Address : String [0..1]
IPv4 (32 bit) or IPv6 (128 bit) service address
Priority : Integer [0..1]
Service priority. Services with lower priority numbers SHOULD
be attempted before those with higher numbers.
Weight : Integer [0..1]
Weight to be used to select between services of equal priority.
Transport : Label [0..1]
OBP Transport binding to be used valid values are HTTP, DNS and
UDP.
Expires : DateTime [0..1]
Date and time at which the specified connection context will
expire.
Cryptographic : Cryptographic [0..1]
Cryptographic Parameters.
4.8. Bind
Binding a device is a two step protocol that begins with the Start
Query followed by a sequence of Ticket queries.
4.9. Message: BindRequest
The following parameters MAY occur in either a StartRequest or
TicketRequest:
Encryption : Label [0..Many]
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.
Hallam-Baker Expires July 25, 2014 [Page 14]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
Otherwise mandatory to implement algorithms MUST be specified
explicitly.
Authentication : Label [0..Many]
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.
4.10. Message: OpenPINRequest
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.
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.
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.
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.
Account : String [0..1]
Account name of the user at the OBP service
Domain : Name [0..1]
Domain name of the OBP broker service
HavePasscode : Boolean [0..1] Default =False
If 'true', the user has entered a passcode value for use with
passcode authentication.
HaveDisplay : Boolean [0..1] Default =False
Specifies if the device is capable of displaying information to
the user or not.
Challenge : Binary [0..1]
Client challenge value to be used in authentication challenge
mechanism as described in section Section 5.1
DeviceID : URI [0..1]
Hallam-Baker Expires July 25, 2014 [Page 15]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
Device identifier unique for a particular instance of a device
such as a MAC or EUI-64 address expressed as a URI
DeviceURI : URI [0..1]
Device identifier specifying the type of device, e.g. an
xPhone.
DeviceImage : ImageLink [0..1]
An image identifying the physical appearance of the device.
DeviceName : String [0..1]
Descriptive name for the device that would distinguish it from
other similar devices, e.g. 'Alice's xPhone".
4.11. Message: OpenPINResponse
An Open request MAY be accepted immediately or be held pending
completion of an inband or out-of-band authentication process.
The OpenResponse returns a ticket and a set of cryptographic
connection parameters in either case. If the
Challenge : Binary [0..1]
Challenge value to be used by the client to respond to the
server authentication challenge.
ChallengeResponse : Binary [0..1]
Server response to authentication challenge by the client as
described in section Section 5.1
Cryptographic : Cryptographic [0..1]
Cryptographic Parameters.
VerificationImage : ImageLink [0..Many]
Link to an image to be used in an image verification mechanism.
4.12. Message: TicketRequest
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.
ChallengeResponse : Binary [0..1]
The response to a serer authentication challenge as described
in section Section 5.1
Hallam-Baker Expires July 25, 2014 [Page 16]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
4.13. Message: TicketResponse
The TicketResponse message returns cryptographic and/or connection
context information to a client.
Cryptographic : Cryptographic [0..Many]
Cryptographic Parameters.
Service : Connection [0..Many]
A Connection describing an OBP service point
4.14. Unbind
Requests that a previous device association be deleted.
4.15. Message: UnbindRequest
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.
4.16. Message: UnbindResponse
Reports on the success of the unbinding operation.
If the server reports success, the client SHOULD delete the ticket
and all information relating to the binding.
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.
5. Mutual Authentication
A Connection Service MAY require that a connection request be
authenticated. Two authentication mechanisms are defined.
PIN Code The client and server demonstrate mutual knowledge of a PIN
code previously exchanged out of band.
Out of Band Confirmation The request for access is confirmed out of
band.
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.
Hallam-Baker Expires July 25, 2014 [Page 17]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
5.1. PIN Authentication
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.
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.
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.
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).
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.
The PIN Mechanism is a three step process:
The client sends an OpenRequest message to the Service containing
a challenge value CC.
The service returns an OpenResponse message containing to the
client a server challenge value SV and a server response value SR.
The client sends a TicketRequest message to the service containing
a client response value CR.
Since no prior authentication key has been established the
OpenRequest and OpenResponse messages are sent without message
authentication.
Hallam-Baker Expires July 25, 2014 [Page 18]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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).
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.
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.
Let A(d,k) be the authentication value obtained by applying the
authentication algorithm with key k to data d.
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:
KPC = A (PIN, CC)
SR = A (Secret + OpenRequest, KPC)
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.
This protocol construction ensures that the party constructing SR:
Knows the PIN code value (through the construction of KPC).
Is responding to the Open Request Message (SR depends on
OpenRequest).
Has knowlege of the secret key which MUST be used to authenticate
the following TicketRequest/TicketResponse interaction that will
establish the actual connection.
Does not provide an oracle the PIN value. That is, the protocol
does not provide a service that reveals the (since the value SR
Hallam-Baker Expires July 25, 2014 [Page 19]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
includes the value SC which is a random nonce generated by the
server and cannot be predicted by the client).
To create the Client Response value, secret key is applied to the PIN
value and server Challenge:
CR = A (PIN + SC + OpenResponse, Secret)
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 Appendix A
This protocol construction ensures that the generator of CR
Knows the PIN value.
Is respoding to the OpenResponse generated by the server.
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.
5.2. Example: Latin PIN Code
The Connection Request example of section Section 3 demonstrates the
use of an alphanumeric PIN code using the Latin alphabet.
The PIN code is [Q80370-1RA606-F04B] and the authentication algorithm
is [HS256]. The value KPC is calculated thus:
PIN: 51 38 30 33 37 30 2d 31 52 41 36 30 36 2d 46 30 34 42
Client Challenge: 22 6e e8 0a 09 98 f6 cf ff f9 fd 67 46 a6 03 d6
KPC: cf 3c 94 e4 21 50 32 34 f5 82 03 19 38 4a f7 be aa b3 7e 73 e0
91 c5 cf a9 d5 60 93 0e 77 8d d2
For the sake of example, we take the OpenRequest message payload to
be {...}. The data over which the hash value is calulated is Secret
+ OpenRequest:
Secret: 23 c3 05 74 7c 68 68 97 81 85 fe 5b c9 df 97 8e
Hallam-Baker Expires July 25, 2014 [Page 20]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
Request Payload: 7b 2e 2e 2e 7d
Server Response: 1d a7 18 08 1a 43 aa c3 33 e7 84 21 67 a1 0f 1e 37
7d 75 98 30 64 06 73 e0 16 50 ff 59 91 a2 51
The data for the client response is PIN + Server Challenge + Payload:
PIN: 51 38 30 33 37 30 2d 31 52 41 36 30 36 2d 46 30 34 42
Server Challenge: 8f 13 3b e7 b3 82 ad 6b e6 44 81 38 f2 f2 bb a8
Request Payload: 7b 2e 2e 2e 7d
Applying the key Secret to the data produces the client response:
Client Response: 0f 8d a6 52 4b d3 64 df a5 2b 25 59 16 21 5a 8e 7d
36 fe 71 27 51 f8 40 7f 49 58 11 a1 4e 7c dd
5.3. Example: Cyrillic PIN Code
If the PIN code in the earlier example was 'parol1' (the Russian for
'password1') in Cyrilic script the value KP would be calculated as
follows
PIN: d0 bf d0 b0 d1 80 d0 be d0 bb d1 8c 31
KPC: cf 3c 94 e4 21 50 32 34 f5 82 03 19 38 4a f7 be aa b3 7e 73 e0
91 c5 cf a9 d5 60 93 0e 77 8d d2
The rest of the protocol would then continue as before.
5.4. Out of Band Confirmation
The Out Of Band Confirmation mechanism is a three step process in
which:
The client makes an OpenRequest message to the service and obtains
an OpenResponse message.
The connection binding is authorized through an out of band
process.
The client makes a TicketRequest to the service and obtains a
TicketResponse message to complete the exchange.
Since no prior authentication key has been established the
OpenRequest and OpenResponse messages are sent without
authentication.
Hallam-Baker Expires July 25, 2014 [Page 21]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
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.
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.
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.
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.
6. Protocol Binding
A single protocol binding is defined:
JSON encoding is used to express JCX messages.
A HTTP session layer with HTTP session continuation is used for
message authentication.
TLS transport is required for confidentiality and service
authentication.
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.
6.1. JSON encoding
Messages are expressed in JSON encoding [RFC4627].
Protocol schema types are mapped to JSON encoding as follows:
Integer Data of type Integer is encoded using the JSON number
encoding.
Name Data of type Name is encoded using the JSON string encoding.
Hallam-Baker Expires July 25, 2014 [Page 22]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
String Data of type String is encoded using the JSON string
encoding.
Binary Data of type Binary is converted to strings using the
Base64url encoding specified in [RFC4648] and encoded using the
JSON string type.
DateTime Data of type DateTime is converted to string using the UTC
time conversion specified in [RFC3339] with a UTC offset of 00:00.
6.2. HTTP Session Layer
Messages are presented over a HTTP session layer [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
[I-D.hallambaker-httpsession] for message authentication.
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.
The use of HTTP session continuation is necessary to achieve mutual
authentication even though TLS transport is required.
Only the HTTP Session header is used. The negotiation of the Session
parameters is performed within JCX.
[TO-DO: Specify TLS binding options?]
[TO-DO: Switch back from using JOSE algorithm names to HTTP Session
algorithm names]
6.3. TLS transport
TLS transport [RFC4627] is used
Support for the PKIX logotype extension [RFC3709] is highly
recommended
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.
Hallam-Baker Expires July 25, 2014 [Page 23]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
7. Service Identification and Discovery
The prefix '[PREFIX-TBD]' has been registered for use as a protocol
identifier for JCX in the URI, SRV and Well Known Location
registries.
The URI form identifying a JCX account identifier is:
PREFIX-TBD:<service>:<account>:< or PREFIX-
TBD:<service>:<account>:<:subaccount>
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.
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:
<account>@<service> or <:subaccount>/<account>@<service>
DNS Service (SRV) record discovery is the preferred method of host
discovery as this provides for fault tollerance and load balancing.
JCX clients SHOULD support use of DNS SRV records for host discovery
and MUST support use of DNS A/AAAA records for host discovery.
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:
https://<service>/.well-known/PREFIX-TBD
8. Acknowledgements
[List of contributors]
9. Security Considerations
9.1. Denial of Service
Hallam-Baker Expires July 25, 2014 [Page 24]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
9.2. Breach of Trust
9.3. Coercion
10. IANA Considerations
[TBS list out all the code points that require an IANA registration]
11. References
11.1. Normative References
[I-D.hallambaker-httpsession]
Hallam-Baker, P., "HTTP Session Management", draft-
hallambaker-httpsession-01 (work in progress), May 2013.
[RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J.,
and T. Wright, "Transport Layer Security (TLS)
Extensions", RFC 4366, April 2006.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[X.509] International Telecommunication Union, "ITU-T
Recommendation X.509 (11/2008): Information technology -
Open systems interconnection - The Directory: Public-key
and attribute certificate frameworks", ITU-T
Recommendation X.509, November 2008.
Hallam-Baker Expires July 25, 2014 [Page 25]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
[X.680] International Telecommunication Union, "ITU-T
Recommendation X.680 (11/2008): Information technology -
Abstract Syntax Notation One (ASN.1): Specification of
basic notation", ITU-T Recommendation X.680, November
2008.
11.2. Non Normative References
[RFC3709] Santesson, S., Housley, R., and T. Freeman, "Internet
X.509 Public Key Infrastructure: Logotypes in X.509
Certificates", RFC 3709, February 2004.
Appendix A. Stateless server
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.
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.
In the PIN Authentication example, two SessionIDs are issued by the
server:
A temporary ID in response to the initial client OpenRequest.
A connection binding ID when the client PIN confirmation is
accepted and the connection binding is created.
Both tickets have the same common wrapper structure:
IV + Encrypt ( Ticket + Mac ( Ticket, Key) Key)
Where
The Initialization vector for the encryption scheme
The Encryption algorithm (AES in CBC Mode)
The ticket data
The Message Authentication algorithm (HMAC-SHA2-256)
Hallam-Baker Expires July 25, 2014 [Page 26]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
A.1. Temporary ID
The temporary ticket returned in the OpenRequest example above is
represented in Base64URL encoding as follows:
SWUpyRVzEjGFw3kzrVVjoSFxY5fakzj8v8O2nNQttqcIn_XoDiIjX2GZX_NUcxMER
e64Ahg-TtQ-xsWO5a03MlndS62k9AhbfIN1EQR6X14UvFKZbkNcBOe09YQT5gXg
OpfPXBKvUrw70M0U78U7kQ
The format of the ticket is 16
IV: 49 65 29 c9 15 73 12 31 85 c3 79 33 ad 55 63 a1
Encrypted Data: 21 71 63 97 da 93 38 fc bf c3 b6 9c d4 2d b6 a7 08 9f
f5 e8 0e 22 23 5f 61 99 5f f3 54 73 13 04 45 ee b8 02 18 3e 4e d4 3e
c6 c5 8e e5 ad 37 32 59 dd 4b ad a4 f4 08 5b 7c 83 75 11 04 7a 5f 5e
14 bc 52 99 6e 43 5c 04 e7 b4 f5 84 13 e6 05 e0 3a 97 cf 5c 12 af 52
bc 3b d0 cd 14 ef c5 3b 91
The encrypted data is decrypted under the master key of the server.
In this example the server has a single fixed key that does not
change over time. There should really be a key index prefixing it to
identify the key number.
The Master Key is: d3 f6 28 42 a0 92 b6 2c 97 3f 6a 7b 05 6e ce e4
The decrypted data contains the algorithm identifiers, shared secret
and message authentication code:
Version Number: 00
Key Identifier: 01
Authentication Algorithm: 00
Encryption Algorithm: 00
Key Data: 23 c3 05 74 7c 68 68 97 81 85 fe 5b c9 df 97 8e
User Name Length: 11
User Name: 61 6c 69 63 65 40 65 78 61 6d 70 6c 65 2e 63 6f 6d
Client Challenge Length: 10
Client Challenge: 22 6e e8 0a 09 98 f6 cf ff f9 fd 67 46 a6 03 d6
Server Challenge Length: 10
Hallam-Baker Expires July 25, 2014 [Page 27]
Internet-Draft JSON Service Connect (JCX) Protocol January 2014
Server Challenge: 8f 13 3b e7 b3 82 ad 6b e6 44 81 38 f2 f2 bb a8
Message Authentication Code: ed 0b fa 4f 60 74 e5 51 f1 60 da 29 b7
ed 94 4d 00 06 46 42 87 41 0d 58 90 8e 73 12 19 02 03 50
A.2. Connection Binding ID
The format of the Connection binding ticket is similar to that of the
Temporary ticket except that it does not contain the Client or Server
challenge nonces.
IV: 77 64 01 12 e2 3c e5 5b 76 68 2c 35 10 87 00 c1
Encrypted Data: 1b b3 08 03 bb 41 cb 6e fd 99 5c 8d 0e a7 19 c6 ee da
cf b1 d0 bd df d5 d3 35 c6 84 a9 a4 41 5c 94 78 91 40 03 e1 b1 53 e3
49 aa 7d 6c 2b 83 9c a5 55 01 f8 b7 df 11 a2 84 51 1c ad ba a1 a3 59
The decrypted data is:
Version Number: 00
Key Identifier: 00
Authentication Algorithm: 00
Encryption Algorithm: 00
Key Data: cd f8 03 1c 0a 75 e3 45 81 d8 98 ec 5b e3 d4 fe
User Name Length: 0c
User Name: 65 40 65 78 61 6d 70 6c 65 2e 63 40
Message Authentication Code: 15 91 b2 26 70 75 cb 23 e1 20 a9 3c 2e
1f 2d 1f d6 12 09 45 73 c3 1f a5 89 b7 81 08 61 9f 1b 8d
Author's Address
Phillip Hallam-Baker
Comodo Group Inc.
Email: philliph@comodo.com
Hallam-Baker Expires July 25, 2014 [Page 28]