DRINKS M. Marrache Internet-Draft Jerusalem College of Technology Intended status: Standards Track D. Schwartz Expires: April 24, 2013 XConnect S. Ali NeuStar October 21, 2012 Session Peering Provisioning (SPP) Protocol over REST draft-marrache-drinks-spp-protocol-rest-01 Abstract The Session Peering Provisioning Framework (SPPF) is a framework that exists to enable the provisioning of session establishment data into Session Data Registries or SIP Service Provider data stores. This SPP Protocol implementation follows the REST architectural principles over HTTP to allow efficient provisioning of session establishment data. The benefits include inter alia better performances under high loads through the use of HTTP caches and proxies and less coupling between clients and servers. This document describes the specification of a protocol for transporting SPPF structures over HTTP(s) following REST architectural principles. 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 April 24, 2013. Copyright Notice Copyright (c) 2012 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 Marrache, et al. Expires April 24, 2013 [Page 1] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 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. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Protocol Architecture . . . . . . . . . . . . . . . . . . . . 6 4. Architectural Principles . . . . . . . . . . . . . . . . . . . 8 4.1. Use of HTTP . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. SPPF Objects as Resources . . . . . . . . . . . . . . . . 8 4.2.1. Service (Root) URI . . . . . . . . . . . . . . . . . . 8 4.2.2. Resources URI . . . . . . . . . . . . . . . . . . . . 8 4.2.3. Resources Representations . . . . . . . . . . . . . . 13 4.3. HTTP methods and operations mapping . . . . . . . . . . . 13 5. Authentication and Session Management . . . . . . . . . . . . 15 6. Operation Request and Response Structures . . . . . . . . . . 16 6.1. Add Operation Structure . . . . . . . . . . . . . . . . . 16 6.1.1. Add Request . . . . . . . . . . . . . . . . . . . . . 16 6.1.2. Add Response . . . . . . . . . . . . . . . . . . . . . 17 6.2. Delete Operation Structure . . . . . . . . . . . . . . . . 18 6.2.1. Delete Request . . . . . . . . . . . . . . . . . . . . 18 6.2.2. Delete Response . . . . . . . . . . . . . . . . . . . 19 6.3. Accept Operation Structure . . . . . . . . . . . . . . . . 19 6.3.1. Accept Request Structure . . . . . . . . . . . . . . . 20 6.3.2. Accept Response . . . . . . . . . . . . . . . . . . . 21 6.4. Reject Operation Structure . . . . . . . . . . . . . . . . 21 6.4.1. Reject Request . . . . . . . . . . . . . . . . . . . . 22 6.4.2. Reject Response . . . . . . . . . . . . . . . . . . . 22 6.5. Get Operation Structure . . . . . . . . . . . . . . . . . 23 6.5.1. Get Request . . . . . . . . . . . . . . . . . . . . . 23 6.5.2. Get Response . . . . . . . . . . . . . . . . . . . . . 24 6.6. Get SED Group Offers Operation Structure . . . . . . . . . 24 6.6.1. Get SED Group Offers Request . . . . . . . . . . . . . 25 6.6.2. Get SED Group Offers Response . . . . . . . . . . . . 26 6.7. Get Server Details Operation Structure . . . . . . . . . . 26 6.7.1. Get Server Details Request . . . . . . . . . . . . . . 26 6.7.2. Get Server Details Response . . . . . . . . . . . . . 27 7. Response Codes and Messages . . . . . . . . . . . . . . . . . 28 7.1. General Status Codes . . . . . . . . . . . . . . . . . . . 28 7.2. HTTP PUT response Status Codes . . . . . . . . . . . . . . 28 Marrache, et al. Expires April 24, 2013 [Page 2] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 7.3. HTTP DELETE response Status Codes . . . . . . . . . . . . 29 7.4. HTTP GET response Status Codes . . . . . . . . . . . . . . 29 8. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 30 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 9.1. Integrity, Privacy, and Authentication . . . . . . . . . . 31 9.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 31 9.3. Deployment Environment Specifics . . . . . . . . . . . . . 32 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 11.1. Normative References . . . . . . . . . . . . . . . . . . . 34 11.2. Informative References . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 Marrache, et al. Expires April 24, 2013 [Page 3] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 1. Introduction TBD Marrache, et al. Expires April 24, 2013 [Page 4] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 2. Terminology 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]. Marrache, et al. Expires April 24, 2013 [Page 5] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 3. Protocol Architecture The following figure illustrates the technical architecture of the RESTful SPP Protocol: +-------------+ (1) | Transport |Example: | Protocol | TCP, TLS, BEEP, etc. +-------------+ | V +-------------+ | HTTP | | | +-------------+ (2) | +-----------------------+ | | V V +----------------+ +----------------+ | HTTP Request | OR | HTTP Response | | | | | +----------------+ +----------------+ Carries | Carries | V V +-------------+ +-------------+ (3) | SPPF | | SPPF | | Types | | Types | +-------------+ +-------------+ Figure 1: Layering and Technical Architecture of the RESTful SPP Protocol RESTful SPP Protocol is supported by different technologies accross multiple layers as follows: Layer 3: This is the data layer in which are defined the SPPF objects transported by the protocol between the involved components. These objects are defined in [I-D.draft-ietf-drinks-spp-framework]. Layer 2: The application protocol layer uses HTTP to allow clients perform the operations defined in the framework document. These operations are mostly provisioning operations. A client initiates an operation by sending an HTTP request to a server. Then, an HTTP response indicating the results of the operation is sent back by the server to the client. SPPF objects defined in the layer above are eventually carried by these HTTP messages. Marrache, et al. Expires April 24, 2013 [Page 6] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 Layer 1: The transport protocol layer represents the communication mechanism between the client and server. SPPF can be layered over any transport protocol that provides a set of basic requirements defined in the Transport Protocol Requirements section. But this document specifies the required mechanism. SPPF is a request/reply framework that allows a client application to submit provisioning data and query requests to a server. The SPPF data structures are designed to be protocol agnostic. Concerns regarding encryption, non-repudiation, and authentication are beyond the scope of this document. For more details, please refer to the "Transport Protocol Requirements" section in the framework document. Marrache, et al. Expires April 24, 2013 [Page 7] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 4. Architectural Principles 4.1. Use of HTTP HTTP(s) is the application protocol used by RESTful web services. HTTP 1.1 includes the "persistent connection" feature, which allows multiple HTTP request/response pairs to be transported across a single HTTP connection. This is an important performance optimization feature, particularly when the connection is an HTTPS connection where the relatively time consuming SSL handshake has occurred. Persistent connections SHOULD be used for the SPPF HTTP connections. HTTP 1.1 [RFC2616] or higher SHOULD be used. 4.2. SPPF Objects as Resources As mentioned in the previous section, the application protocol used by this protocol implementation is HTTP. Since HTTP has been conceived to operate on resources exposed on the web, the SPPF objects need to be exposed as resources. The SPPF objects then become available to clients for performing operations defined in the framework document. Each resource exposed on the web is identified by a Uniform Resource Identifier (URI). Therefore, a URI is defined for each SPPF object. In order to be able to identify uniquely an SPPF object, the corresponding URI must include the attributes of a candidate key for this SPPF object. The attributes that form the key of each SPPF object are specified in the framework document. These attributes are included in the URI as path parameters. 4.2.1. Service (Root) URI In the next sections, the service URI may be used. It is the root URI where the RESTful service is located. 4.2.2. Resources URI In order to provide a URI for each SPPF object, a URI template is defined for each one of them. The URI templates defined in the following sub-sections are relative to the service URI defined in the Service URI section. 4.2.2.1. Destination Group As mentioned in the framework document, a destination group is uniquely identified by the following attributes: the registrant and Marrache, et al. Expires April 24, 2013 [Page 8] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 the destination group's name. Therefore, the destination group resources are identified by the following URI template: /{rant}/DG/{name} where: o rant: registrant organization of the destination group. o name: destination group's name. 4.2.2.2. Telephone Number As mentioned in the framework document, a telephone number (TN) is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the telephone number. Therefore, the telephone number resources are identified by the following URI template: /{rant}/TN/{dgName};{tn} where: o rant: registrant organization of the telephone number. o dgName: name of the associated destination group. o tn: telephone number. 4.2.2.3. Telephone Number Prefix As mentioned in the framework document, a telephone number prefix (TNP) is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the telephone number prefix. Therefore, the telephone number prefix resources are identified by the following URI template: /{rant}/TNP/{dgName};{prefix} where: o rant: registrant organization of the telephone number prefix. o dgName: name of the associated destination group. o prefix: telephone number prefix. Marrache, et al. Expires April 24, 2013 [Page 9] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 4.2.2.4. Telephone Number Range As mentioned in the framework document, a telephone number range (TNR) is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, the telephone that starts the range and the one that ends the range. Therefore, the telephone number range resources are identified by the following URI template: /{rant}/TNR/{dgName};{startTn};{endTn} where: o rant: registrant organization of the telephone number range. o dgName: name of the associated destination group. o startTn: first telephone number of the range. o endTn: last telephone number of the range. 4.2.2.5. Routing Number As mentioned in the framework document, a routing number is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the routing number. Therefore, the routing number resources are identified by the following URI template: /{rant}/RN/{dgName};{rn} where: o rant: registrant organization of the routing number. o dgName: name of the associated destination group. o rn: routing number. 4.2.2.6. URI Public Identifier As mentioned in the framework document, a public identifier URI is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the URI. Therefore, the public identifier URI resources are identified by the following URI template: /{rant}/URI/{dgName};{uri} Marrache, et al. Expires April 24, 2013 [Page 10] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 where: o rant: registrant organization of the public identifier URI. o dgName: name of the associated destination group. o uri: URI. 4.2.2.7. SED Group As mentioned in the framework document, a SED Group is uniquely identified by the following attributes: the registrant and the SED Group's name. Therefore, the SED Group resources are identified by the following URI template: /{rant}/SG/{name} where: o rant: registrant organization of the SED Group. o name: SED Group's name. 4.2.2.8. SED Record As mentioned in the framework document, a SED Record is uniquely identified by the following attributes: the registrant and the SED Record's name. Therefore, the SED Record resources are identified by the following URI template: /{rant}/SR/{name} where: o rant: registrant organization of the SED Record. o name: SED Record's name. Note that there is no need to use one URI template per subtype of Sed Record since they are all identified by the same attributes. 4.2.2.9. SED Group Offer As mentioned in the framework document, a SED Group Offer is uniquely identified by the following attributes: the offering registrant (i.e. the registrant of the offered SED Group), the name of the offered SED Group and the registrant to which the SED Group is offered. Therefore, the SED Group Offer resources are identified by the Marrache, et al. Expires April 24, 2013 [Page 11] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 following URI template: /{rant}/SGOffer/{sedGrpName};{offeredTo} where: o rant: offering registrant organization. o sedGrpName: offered SED Group's name. o offeredTo: organization to which the SED Group is offered. 4.2.2.10. SED Group Offer Acceptation A SED Group Offer may be accepted by the organization to which the SED Group has been offered. The acceptation of a SED Group Offer is represented by an Acceptation resource. An acceptation is identified by the same attributes that identify a SED Group Offer. Therefore, the Acceptation resources are identified by the following URI template: /{rant}/Acceptation/{sedGrpName};{offeredTo} where: o rant: offering registrant organization. o sedGrpName: offered SED Group's name. o offeredTo: organization to which the SED Group is offered. 4.2.2.11. SED Group Offer Rejection A SED Group Offer may be rejected by the organization to which the SED Group has been offered. The rejection of a SED Group Offer is represented by a Rejection resource. A Rejection is identified by the same attributes that identify a SED Group Offer. Therefore, the Rejection resources are identified by the following URI template: /{rant}/Rejection/{sedGrpName};{offeredTo} where: o rant: offering registrant organization. o sedGrpName: offered SED Group's name. Marrache, et al. Expires April 24, 2013 [Page 12] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 o offeredTo: organization to which the SED Group is offered. 4.2.2.12. Server Status The Server Status is exposed as a singleton resource. Therefore, there is no need to define a URI template. The resource is identified by the following URI: /ServerStatus This resource contains information about the server as described later. 4.2.3. Resources Representations For some operations defined by SPPF, resource representations may be present in the HTTP messages. When this is the case, the resource representation is carried in the HTTP message's body. A resource may have many available representations when each one may use a specific format (e.g. XML, JSON). Therefore, HTTP messages that carry resource representations MUST have their Content-Type HTTP header set to the appropriate media type. 4.3. HTTP methods and operations mapping Most operations exposed by this protocol implementation are regular CRUD operations on resources. As mentioned earlier, an operation on a resource is initiated by a client when he sends an HTTP request that targets the resource's URI. In order to indicate the desired operation to perform on a given resource, a client selects one of the following HTTP methods: o GET : Retrieve a representation of the resource identified by the URI present in the HTTP request. o PUT : If no resource is associated to the URI present in the HTTP request, create the resource using the representation provided in the HTTP request's body, and associate the resource to the URI. Otherwise, update the resource using the provided representation. Since the URI of a non existing resource is known by the client before creation (because the values of the attributes that form the key are known by the client before creation), this HTTP method is also used to create resources (instead of POST). o DELETE : Delete the resource identified by the URI present in the HTTP request. Marrache, et al. Expires April 24, 2013 [Page 13] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 Note that not all HTTP methods are allowed on a given resource. For example, a resource may be exposed for read only. In such case, the only HTTP method that is allowed for this resource is GET. The resources that may be targetted by each one of the operations defined above, are as follows: o GET : allowed for all resources but the SED Group Offer Acceptations and Rejections resources. o PUT : allowed for all resources but the Server Status resource. o DELETE : allowed for all resources but the SED Group Offer Acceptations, Rejections and Server Status resources. Marrache, et al. Expires April 24, 2013 [Page 14] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 5. Authentication and Session Management To achieve integrity and privacy, conforming SPP Protocol Clients and Servers MUST support HTTP over TLS [RFC5246] as the secure transport mechanism. This combination of HTTP and TLS is referred to as HTTPS. And to accomplish authentication, conforming SPPF Clients and Servers MUST use HTTP Digest Authentication as defined in [RFC2617]. As a result, the communication session is established through the initial HTTP connection setup, the digest authentication, and the TLS handshake. When the HTTP connection is broken down, the communication session ends. Marrache, et al. Expires April 24, 2013 [Page 15] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 6. Operation Request and Response Structures An SPPF client interacts with an SPPF server by using one of the supported transport mechanisms to send one or more requests to the server and receive corresponding replies from the server. The basic set of operations that an SPPF client can submit to an SPPF server and the semantics of those operations are defined in the "Framework Operations" section of the framework document. The following sub- sections describe how these operations should be performed in the context of this protocol implementation. 6.1. Add Operation Structure In order to add (update) an object to (present in) the registry, an authorized entity sends an add (update) request to the registry. This request consists of an HTTP PUT request on the URI that identifies the resource to add (update). The representation of the resource to add (update) is carried in the HTTP request's body. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. 6.1.1. Add Request The format of an HTTP request used to add (update) an SPPF object to (present in) the registry is as follows: PUT ${ResourceURI}[?clientTransId=${clientTransId}] HTTP/1.1 ..... [minorVer: ${minorVer}] Content-Type: ? Content-Length: ? ${ResourceRepresentation} The data elements within the HTTP PUT request are described as follows: o ResourceURI: The relative URI of the resource targeted by the HTTP PUT request. See the Resources URI section. o clientTransId: An optional query parameter representing a client-generated transaction ID that, within the context of the Marrache, et al. Expires April 24, 2013 [Page 16] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log or correlate requests and their responses. SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. SPPF server will not check this value for uniqueness. o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. o ResourceRepresentation: The representation of the resource to add (update). 6.1.2. Add Response The format of an HTTP response to an add (update) request is as follows: HTTP/1.1 ${StatusCode} .... [clientTransId: ${clientTransId}] serverTransId: ${serverTransId}] Content-Length: 0 The data elements within the HTTP PUT response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o clientTransId: A header parameter representing the client transaction ID of the corresponding HTTP request, if provided. This value is simply an echo of the client transaction ID that SPPF client passed into the SPPF request. When included in the request, the SPPF server MUST return it in the corresponding response message. Marrache, et al. Expires April 24, 2013 [Page 17] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 o serverTransId: A header parameter representing the server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server. 6.2. Delete Operation Structure In order to remove an object from the registry, an authorized entity sends a delete request to the registry. This request consists of an HTTP DELETE request on the URI that identifies the resource to delete. The body of the HTTP request is empty since the resource to delete is uniquely identified by the URI included in the request. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. 6.2.1. Delete Request The format of an HTTP request used to delete an SPPF object from the registry is as follows: DELETE ${ResourceURI}[?clientTransId=${clientTransId}] HTTP/1.1 ..... [minorVer: ${minorVer}] Content-Length: 0 The data elements within the HTTP DELETE request are described as follows: o ResourceURI: The relative URI of the resource targeted by the HTTP DELETE request. See the Resources URI section. o clientTransId: An optional query parameter representing a client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log or correlate requests and their responses. SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. SPPF server will not check this value for uniqueness. o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in Marrache, et al. Expires April 24, 2013 [Page 18] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. 6.2.2. Delete Response The format of an HTTP response to a delete request is as follows: HTTP/1.1 ${StatusCode} .... [clientTransId: ${clientTransId}] serverTransId: ${serverTransId}] Content-Length: 0 The data elements within the HTTP DELETE response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o clientTransId: A header parameter representing the client transaction ID of the corresponding HTTP request, if provided. This value is simply an echo of the client transaction ID that SPPF client passed into the SPPF request. When included in the request, the SPPF server MUST return it in the corresponding response message. o serverTransId: A header parameter representing the server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server. 6.3. Accept Operation Structure In SPPF, a SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered (refer "Framework Data Model Objects" section of the framework document for a description of the SED Group Offer object). The Accept operation is used to accept such SED Group Offers by, or on behalf of, the Registrant. This request consists of an HTTP PUT request on the URI that identifies the Acceptation resource for the Marrache, et al. Expires April 24, 2013 [Page 19] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 concerned SED Group Offer. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. 6.3.1. Accept Request Structure The format of an HTTP request used to accept a SED Group Offer is as follows: PUT ${AcceptationURI}[?clientTransId=${clientTransId}] HTTP/1.1 ..... [minorVer: ${minorVer}] Action: Accept Content-Length: 0 The data elements within the HTTP PUT request are described as follows: o AcceptationURI: The relative URI of the Acceptation resource targeted by the HTTP PUT request. See the Resources URI section. o clientTransId: An optional query parameter representing a client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log or correlate requests and their responses. SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. SPPF server will not check this value for uniqueness. o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. Marrache, et al. Expires April 24, 2013 [Page 20] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 6.3.2. Accept Response The format of an HTTP response to an Accept request is as follows: HTTP/1.1 ${StatusCode} .... [clientTransId: ${clientTransId}] serverTransId: ${serverTransId}] Content-Length: 0 The data elements within the HTTP PUT response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o clientTransId: A header parameter representing the client transaction ID of the corresponding HTTP request, if provided. This value is simply an echo of the client transaction ID that SPPF client passed into the SPPF request. When included in the request, the SPPF server MUST return it in the corresponding response message. o serverTransId: A header parameter representing the server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server. 6.4. Reject Operation Structure In SPPF, a SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered (refer "Framework Data Model Objects" section of the framework document for a description of the SED Group Offer object). The Reject operation is used to reject such SED Group Offers by, or on behalf of, the Registrant. This request consists of an HTTP PUT request on the URI that identifies the Rejection resource for the concerned SED Group Offer. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. Marrache, et al. Expires April 24, 2013 [Page 21] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 6.4.1. Reject Request The format of an HTTP request used to reject a SED Group Offer is as follows: PUT ${RejectionURI}[?clientTransId=${clientTransId}] HTTP/1.1 ..... [minorVer: ${minorVer}] Action: Reject Content-Length: 0 The data elements within the HTTP PUT request are described as follows: o RejectionURI: The relative URI of the Rejection resource targeted by the HTTP PUT request. See the Resources URI section. o clientTransId: An optional query parameter representing a client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log or correlate requests and their responses. SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. SPPF server will not check this value for uniqueness. o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. 6.4.2. Reject Response The format of an HTTP response to a reject request is as follows: Marrache, et al. Expires April 24, 2013 [Page 22] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 HTTP/1.1 ${StatusCode} .... [clientTransId: ${clientTransId}] serverTransId: ${serverTransId}] Content-Length: 0 The data elements within the HTTP PUT response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o clientTransId: A header parameter representing the client transaction ID of the corresponding HTTP request, if provided. This value is simply an echo of the client transaction ID that SPPF client passed into the SPPF request. When included in the request, the SPPF server MUST return it in the corresponding response message. o serverTransId: A header parameter representing the server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server. 6.5. Get Operation Structure In order to query the details of an object from the Registry, an authorized entity sends a get request to the registry. This request consists of an HTTP GET request targetting the URI that identifies the queried resource. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. Moreover, if the queried object is found in the registry, the HTTP response's body contains the representation of the result object. The following sub-sections describe the expected format of the HTTP requests and responses. 6.5.1. Get Request The format of an HTTP request used to get an SPPF object is as follows: GET ${ResourceURI} HTTP/1.1 ..... [minorVer: ${minorVer}] Marrache, et al. Expires April 24, 2013 [Page 23] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 Content-Length: 0 The data elements within the HTTP GET request are described as follows: o ResourceURI: The relative URI of the resource targeted by the HTTP GET request. See the Resources URI section. o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. 6.5.2. Get Response The format of an HTTP response to a get request is as follows: HTTP/1.1 ${StatusCode} .... Content-Length: ? ${ResourceRepresentation} The data elements within the HTTP GET response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o ResourceRepresentation: The representation of the queried resource. 6.6. Get SED Group Offers Operation Structure In addition to the ability to query the details of one or more SED Group offers using a SED Group Offer key in a Get request, this operation also provides an additional, more flexible, structure to Marrache, et al. Expires April 24, 2013 [Page 24] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 query for SED Group Offer objects. 6.6.1. Get SED Group Offers Request Using the details passed into this structure, the server will attempt to find SED Group Offer objects that satisfy all the criteria passed into the request. If no criteria is passed in then the server will return the list of SED Group Offer objects that belong to the registrant. If there are no matching SED Group Offers found then an empty result set will be returned. The format of an HTTP request used to get SED Group Offers is as follows: GET /SEDGrpOffer[?offeredBy=${offeredBy}[&offeredTo=${offeredTo} \ [&status=${status}]]] HTTP/1.1 ..... [minorVer: ${minorVer}] Content-Length: 0 The data elements within the HTTP GET request are described as follows: o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the SPPF server menu operation described later in the document. o offeredBy: An optional query parameter representing one or more comma separated organization IDs. Only offers that are offered by the organization IDs in this list should be included in the result set. The result set is also subject to other query criteria in the request. o offeredTo: An optional query parameter representing one or more comma separated organization IDs. Only offers that are offered to the organization IDs in this list should be included in the result set. The result set is also subject to other query criteria in the request. Marrache, et al. Expires April 24, 2013 [Page 25] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 o status: An optional query parameter representing an offer status (offered or accepted). Only offers in the specified status should be included in the result set. If this element is not present then the status of the offer should not be considered in the query. The result set is also subject to other query criteria in the request. o SedGrpOfferKey: TBD 6.6.2. Get SED Group Offers Response The format of an HTTP response to a get SED Group Offers request is as follows: HTTP/1.1 ${StatusCode} .... Content-Length: ? ${SEDGrpOffersRepresentation} The data elements within the HTTP GET response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o SEDGrpOffersRepresentation: TBD. 6.7. Get Server Details Operation Structure In order to query certain details of the SPPF server, like the SPPF server's status and the major/minor version supported by the server, the Server Details operation structure SHOULD be used. 6.7.1. Get Server Details Request The format of an HTTP request used to get the server status is as follows: GET /ServerStatus HTTP/1.1 ..... [minorVer: ${minorVer}] Marrache, et al. Expires April 24, 2013 [Page 26] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 Content-Length: 0 The data elements within the HTTP GET request are described as follows: o minorVer: An optional header parameter representing a minor version identifier, indicating the minor version of the SPPF API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML namespace to identify the version of SPPF that the client is using. If the element is not present, the server assumes that the client is using the latest minor version supported by the SPPF server for the given major version. The versions supported by a given SPPF server can be retrieved by the client using the Get Server Status request without passing in the minorVer element. 6.7.2. Get Server Details Response The format of an HTTP response to a Get Server Status request is as follows: HTTP/1.1 ${StatusCode} .... Content-Length: ? ${ServerStatusRepresentation} The data elements within the HTTP GET response are described as follows: o StatusCode: One of the available HTTP status codes indicating the result of the request. See Response Codes and Messages section. o ServerStatusRepresentation: The representation of the Server Status resource. Marrache, et al. Expires April 24, 2013 [Page 27] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 7. Response Codes and Messages HTTP provides a set of status codes that are used to indicate an overall result of the request to the client. This protocol implementation uses the status codes defined in [RFC2616]. 7.1. General Status Codes The following status codes may be returned in the HTTP responses of all operations defined in this document. o 200 OK: For an HTTP PUT request, this status code is returned if the resource has been updated. For an HTTP GET or DELETE request, this status code is returned if the operation has been successfully performed. o 400 Bad Request: This status code is returned if the HTTP request received by the server is invalid. o 401 Unauthorized: This status code is returned when client authentication is required and has failed or has not yet been provided. o 403 Forbidden: This status code is returned when the client is authenticated but not authorized to perform the desired operation. o 405 Method Not Allowed: This status code is returned if the method present in the HTTP request is not allowed for the resource identified by the given URI. o 500 Internal Server Error: This status code is returned if an unexpected internal system or server error happened. o 503 Service Unavailable: This status code is returned if the server is temporarily unable to process incoming HTTP requests. 7.2. HTTP PUT response Status Codes o 201 Created: This status code is returned if the resource at the specified URI doesn't exist and therefore has been created (instead of updated). o 415 Unsupported Media Type: This status code is returned if the Content-Type header has a value corresponding to a media type not supported by the server. Marrache, et al. Expires April 24, 2013 [Page 28] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 7.3. HTTP DELETE response Status Codes o 404 Not Found: This status code is returned if the resource identified by the given URI doesn't exist and therefore cannot be deleted. 7.4. HTTP GET response Status Codes o 404 Not Found: This status code is returned if the resource identified by the given URI doesn't exist and therefore cannot be retrieved. Marrache, et al. Expires April 24, 2013 [Page 29] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 8. Protocol Operations Refer the "Framework Operations" section of the framework document for a description of all SPPF operations, and any necessary semantics that MUST be adhered to in order to conform with the SPPF specification. Marrache, et al. Expires April 24, 2013 [Page 30] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 9. Security Considerations RESTful SPP Protocol is used to query and update session peering data and addresses, so the ability to access this protocol should be limited to users and systems that are authorized to query and update this data. Because this data is sent in both directions, it may not be sufficient for just the client or user to be authenticated with the server. The identity of the server should also be authenticated by the client, which is often accomplished using the TLS certificate exchange and validation described in [RFC2818]. SPP Protocol messages may include sensitive information, routing data, lists of resolvable addresses, etc. So when used in a production setting and across non-secure networks, SPP Protocol should only be used over communications channels that provide strong encryption for data privacy. 9.1. Integrity, Privacy, and Authentication The RESTful SPP Protocol relies on an underlying secure transport for integrity and privacy. Such transports are expected to include TLS/ HTTPS. In addition to the application level authentication imposed by an SPPF server, there are a number of options for authentication within the transport layer and the messaging envelope. These include TLS client certificates and HTTP Digest Access Authentication headers. At a minimum, all conforming RESTful SPP Protocol implementations MUST support HTTPS. 9.2. Vulnerabilities The above protocols may have various vulnerabilities, and these may be inherited by the RESTful SPP Protocol. RESTful SPP Protocol itself may have vulnerabilities because an authorization model is not explicitly specified in the current specification. Sections 5 and 10.1 describe requirements for HTTPS support using TLS. Non-anonymous TLS servers can optionally request a certificate from a TLS client; that option is not a requirement for this protocol. This presents a denial of service risk in which unauthenticated clients can consume server CPU resources by creating TLS sessions. The risk is increased if the server supports client- initiated renegotiation. This risk can be mitigated by disabling client-initiated renegotiation on the server and by ensuring that other means (such as firewall access control lists) are used to restrict unauthenticated client access to servers. In conjunction with the above, it is important that REST SPP Protocol Marrache, et al. Expires April 24, 2013 [Page 31] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 implementations implement an authorization model that considers the source of each query or update request and determines whether it is reasonable to authorize that source to perform that specific query or update. 9.3. Deployment Environment Specifics Some deployments of REST SPP Protocol could choose to use transports without encryption. This presents vulnerabilities but could be selected for deployments involving closed networks or debugging scenarios. However, the vulnerabilities of such a deployment could be a lack of integrity and privacy of the data transported in this type of deployment. Marrache, et al. Expires April 24, 2013 [Page 32] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 10. Acknowledgements TBD Marrache, et al. Expires April 24, 2013 [Page 33] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 11. References 11.1. Normative References [I-D.draft-ietf-drinks-spp-framework] Cartwright, K., Bhatia, V., Ali, S., and D. Schwartz, "Session Peering Provisioning Framework", draft-ietf-drinks-spp-framework-02 (work in progress), July 2012. [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. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. 11.2. Informative References [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [Roy Fielding] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", University of California , 2000, . [W3C.REC-xml-20081126] Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, November 2008, . Marrache, et al. Expires April 24, 2013 [Page 34] Internet-Draft draft-marrache-drinks-spp-protocol-rest October 2012 Authors' Addresses Mickael Marrache Jerusalem College of Technology Havaad Haleumi St. 21 Jerusalem, 91160 Israel Email: mickaelmarrache@gmail.com David Schwartz XConnect 316 Regents Park Road London, N3 2XJ United Kingdom Email: dschwartz@xconnect.net Syed Wasim Ali NeuStar 46000 Center Oak Plaza Sterling, VA 20166 USA Email: syed.ali@neustar.biz Marrache, et al. Expires April 24, 2013 [Page 35]