| Internet Engineering Task Force | P. M. Hallam-Baker |
| Internet-Draft | Comodo Group Inc. |
| Intended status: Standards Track | May 17, 2013 |
| Expires: November 18, 2013 |
Web Services Connect Protocol
draft-hallambaker-wsconnect-00
Many Web Services share a requirement for establishing and maintaining a persistent connection between the client and service.
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 November 18, 2013.
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.
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.
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 RFC 2119 [RFC2119].
The principle function of the OBP Connection Maintenance Protocol is to establish and maintain the cryptographic parameters used to authenticate and encrypt
The user needs to authenticate the broker service regardless of any authentication requirements of the broker.
The OBP connection maintenance protocol transport MUST provide a trustworthy means of verifying the identity of the broker (e.g. an Extended Validation SSL certificate).
If the device supports a display capability, authentication of the device and user MAY be achieved by means of an authentication image. Such an authentication image is generated by the broker and passed to the client in the OpenResponse message. The user then verifies that the image presented on the device display is the same as that presented on the account maintenance console.
If device 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 into the device that was previously delivered to the user out of band.
The passcode authentication mechanism allows the device to establish a proof that it knows the passcode without disclosing the passcode. This property provides protection against Man-In-The-Middle type disclosure attacks.
Alice is an employee of Example Inc. which runs its own local omnibroker service 'example.com'. To configure her machine for use with this service, Alice contacts her network administrator who assigns her the account identifier 'alice' and obtains a PIN number from the service 'Q80370-1RA606-F04B'
Alice enters the values 'alice@example.com' and 'Q80370-1RA606-F04B' into her Omnibroker-enabled Web browser.
The Web browser uses the local DNS to resolve 'example.com' and establishes a HTTPS connection to the specified IP address. The client verifies that the certificate presented has a valid certificate chain to an embedded trust anchor under an appropriate certificate policy (e.g. compliant with Extended Validation Criteria defined by CA-Browser Forum).
Having established an authenticated and encrypted TLS session to the Omnibroker service, the client sends an OpenRequest message to begin the process of mutual authentication. This message specifies the cryptographic parameters supported by the client (Authentication, Encryption) and a nonce value (Challenge), device identification parameters (DeviceID, DeviceURI, DeviceName) and the name of the account being requested.
The client does not specify the PIN code in the request, nor is the request authenticated. Instead the client informs the server that it has a PIN code that can be supplied if necessary.
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"}}
The service receives the request. If the request is consistent with the access control policy for the server it returns a reply that specifies the chosen cryptographic parameters (Cryptographic), responds to the client issued by the client to establish server proof of knowsledge of the PIN (ChallengeResponse) and issues a challenge to the client (Challenge).
The cryptographic parameters specify algorithms to be used for encryption and authentication, a shared secret and a ticket value. Note that while the shared secret is exchanged in plaintext form in the HTTP binding, the connection protocol MUST provide encryption.
HTTP/1.1 203 Passcode
Content-Type: application/json;charset=UTF-8
Content-Length: 500
{
"OpenResponse": {
"Status": 203,
"StatusDescription": "Passcode",
"Cryptographic": [{
"Secret": "11bmdFi9Et7KIUg8aeN2AQ==",
"Encryption": "A128CBC",
"Authentication": "HS256",
"Ticket":
"TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIO
qPa4oB29dgs/ei6ieINZtmvXNCm2NUkWA=="}],
"Challenge": "alX8aAWH6acSqO3FTT94HA==",
"ChallengeResponse": "enT5myMw8w2hV4H32Ntx/g=="}}
To complete the transaction, the client sends a TicketRequest message to the serice containing a response to the PIN challenge sent by the service (ChallengeResponse). The TicketRequest message is authenticated under the shared secret specified in the OpenResponse message.
Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 78
Content-Integrity:
mac=cjkMkfnnYP8JYWZAbRLvtpqImmOK3rsrOT1XcvAgHDk=;
ticket=TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIOqPa4
oB29dgs/ei6ieINZtmvXNCm2NUkWA==
{
"TicketRequest": {
"ChallengeResponse": "TctLOG74cwpm26YNpEibcQ=="}}
If the response to the PIN challenge is correct, the service responds with a message that specifies a set of cryptographic parameters to be used to authenticate future interactions with the service (Cryptographic) and a set of connection parameters for servers supporting the Query Service (Service).
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).
HTTP/1.1 200 Complete
Content-Type: application/json;charset=UTF-8
Content-Length: 1907
Content-Integrity:
mac=nKhjR1r2eYPga0rmDfHT4HOvgQ+EuUoQPwzIl0btljs=;
ticket=TUMnorO0SjHHS7D2uFcGlRYJ0Hd3eibwe0ogptoNMQuCYmCHfHAJcJlyvi
j8WoXDglTSOkctnmoBzl8W0NLSlcgSyZcmsAyoWs8y1Rn2ZlO2WBgoWrFIOqPa4
oB29dgs/ei6ieINZtmvXNCm2NUkWA==
{
"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="}}]}
}
When Alice's machine is to be transfered to another employee, the Unbind transaction is used. The only parameter is the Ticket identifying the device association (Ticket).
Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 25
Content-Integrity:
mac=bZU61eCOW4nVnfdJNS719HL4IsNVxtoTgoRt+mqLbWY=;
ticket=0ulMVMMfY/pLHZ0FlIy2zDnNycYz9Znvs3JJYQGlZ+dWaxMNxm/jLEsJd/
0qsAc5qp8fjBoMN49V9DkDgM4UYJxVriqfr64RyTTgug2taHY=
{
"UnbindRequest": {}}
Since the unbind response represents the termination the relationship with the Omnibroker, the response merely reports the success or failure of the request.
HTTP/1.1 0
Content-Type: application/json;charset=UTF-8
Content-Length: 26
Content-Integrity:
mac=9P1FmroeFU7y9qHgXdSFXH2qSImh0cQpaSgZrx5IswM=;
ticket=0ulMVMMfY/pLHZ0FlIy2zDnNycYz9Znvs3JJYQGlZ+dWaxMNxm/jLEsJd/
0qsAc5qp8fjBoMN49V9DkDgM4UYJxVriqfr64RyTTgug2taHY=
{
"UnbindResponse": {}}
The 'Ticket' value presented in the foregoing examples is a sequence of binary data generated by the service is opaque to the client. Services MAY generate ticket values with a substructure that enable the service to avoid the need to maintain server side state.
In the foregoing example, the ticket structures generated by the service encode the cryptographic parameter data, the shared secret, account identifier and an authentication value. The initial ticket value generated additionally encodes the values of the client and service challeng values for use in calculating the necessary ChallengeResponse.
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.
Parameters describing a cryptographic context.
Contains information describing a network connection.
Binding a device is a two step protocol that begins with the Start Query followed by a sequence of Ticket queries.
The following parameters MAY occur in either a StartRequest or TicketRequest:
The following parameters MAY occur in either a StartResponse or TicketResponse:
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.
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
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.
The TicketResponse message returns cryptographic and/or connection context information to a client.
Requests that a previous device association be deleted.
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.
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.
A Connection Service MAY require that a connection request be authenticated. Three authentication mechanisms are defined.
[Motivation]
Although the PIN value is never exposed on the wire in any form, the protcol considers the PIN value to be a text encoded in UTF8 encoding.
[Considerations for PIN character set choice discussed in body of draft, servers MUST support numeric only, clients SHOULD support full Unicode]
The PIN Mechanism is a three step process:
Since no prior authentication key has been the OpenRequest and OpenResponse messages are initially sent without authentication and authentication values established the Challenge-Response mechanism.
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 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 + SC + 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:
To create the Client Response value, secret key is applied to the PIN value and server Challenge:
CR = A (PIN + SC + OpenRequest, 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 Section 4.4
This protocol construction ensures that the of CR
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.
The Connection Request example of section Section 3.1.3 demonstrates the use of an alphanumeric PIN code using the Latin alphabet.
The PIN code is [] and the authentication algorithm is []. The value KP is thus:
[TBS]
The data over which the hash value is calulated is Secret + SC + OpenRequest:
[TBS]
Applying the derrived key to the data produces the server response:
The data for the client response is PIN + SC:
[TBS]
Applying the secret key to the data produces the client response:
[TBS]
If the PIN code in the earlier example was [] the value KP would be:
[TBS]
The Server Response would be:
[TBS]
The rest of the protocol would then continue as before.
The protocol is designed to permit but not require a stateless implementation by the server using the Ticket value generated by the server to pass state from the first server transaction to the second.
In the example shown in Section 3.1.3, the server generates a 'temporary ticket' containing the following information:
If a server uses the Ticket to transmit state in this way it MUST protect the confidentiality of the ticket using a strong means of encryption and authentication.
The Established Key mechanism is used when the parties have an existing shared key or public key credential.
The [Open request open response are authenticated under the respective keys]
SR=CC, CR=SC
The Out Of Band Confirmation mechanism is a three step process in which:
Since no prior authentication key has been the OpenRequest and OpenResponse messages are sent without authentication.
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.
[List of contributors]
[TBS list out all the code points that require an IANA registration]
| [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. |
| [RFC4366] | Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J. and T. Wright, "Transport Layer Security (TLS) Extensions", RFC 4366, April 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. |
| [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. |