SPARQL 1.1 Secure Event Protocol

Introduction

The SPARQL 1.1 SE Protocol wraps the SPARQL 1.1 Protocol [[sparql11-protocol]] to support subscriptions and secure connections. It is framed within W3C Recommendations as shown in the following figure.

Fig. 1 - The SPARQL 1.1 Secure Event Protocol

The SPARQL 1.1 SE protocol targets the application contexts where security MUST be supported (e.g., the

The SPARQL 1.1 SE Protocol aims at:

Extending the SPARQL 1.1 Protocol [[sparql11-protocol]] to support SPARQL subscriptions
Providing clients authentication based on OAuth 2.0 [[!RFC6749]]
Providing data encryption, server authentication and message integrity

On one hand, the SPARQL 1.1 SE Protocol MUST transparently support the HTTP methods provided by the [[sparql11-protocol]] to transport SPARQL 1.1 Queries [[sparql11-query]] and Updates [[sparql11-update]]. On the other hand, subscriptions need a two-way communication between subscribers and the SEPA broker. A SEPA broker is RECOMMENDED to provide this kind of communication by using Websockets [[!RFC6455]].

Document conventions

When this document uses the words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and RECOMMENDED, and the words appear as emphasized text, they must be interpreted as described in RFC 2119 [[!RFC2119]].

Terminology

SEPA: SPARQL Event Processing Architecture
SEPA broker: The server component of the SEPA. It implements the publish-subscribe mechanisms and algorithms. Clients interact with a SEPA broker with the SPARQL 1.1 SE Protocol
SPARQL 1.1 Subscribe Language: The subscription language introduced by the SEPA
SPARQL 1.1 SE Protocol: The protocol implemented by a SEPA broker and defined in this document
SPARQL 1.1 Update Language: As defined by [[sparql11-update]]
SPARQL 1.1 Query Language: As defined by [[sparql11-query]]

SPARQL 1.1 Query

SPARQL 1.1 Queries [[sparql11-query]] SHOULD be transparently supported by a SPARQL SE Protocol Service as described in [[sparql11-protocol]].

A SEPA broker is RECOMMENDED to :

implement the POST method of the SPARQL 1.1 Protocol [[sparql11-protocol]]
follow the SPARQL 1.1 Query Results JSON format [[sparql11-results-json]]
reply as shown here in case of error

An example of a query request and response follows:

Request

POST http://vaimee.org:8000/query

Headers

Content-Type: application/sparql-query
Accept: application/sparql-results+json

Body

SELECT * WHERE {?vaimee ?deda ?didi}

Test the example with

Test the query example with the following

curl -X POST -d "select * where {?vaimee ?deda ?didi}" -H "Content-Type: application/sparql-query" -H "Accept: application/sparql-results+json" http://localhost:8000/query

Headers

Content-Type: application/json

Body

{ "head": { "vars": ["vaimee","deda","didi"] },
  "results": {
   "bindings": [{ 
     "vaimee": {"type": "uri", "value" : "http://wot.arces.unibo.it/example#Subject"}, 
     "deda": {"type": "uri", "value": "http://wot.arces.unibo.it/example#Predicate"}, 
     "didi": {"type": "literal","value": "ვაიმეე"} }]}}

SPARQL 1.1 Update

SPARQL 1.1 Updates [[sparql11-update]] SHOULD be transparently supported by a SPARQL SE Protocol Service as described in [[sparql11-protocol]].

A SEPA broker is RECOMMENDED supporting the POST method of the SPARQL 1.1 Protocol [[sparql11-protocol]] and replying in case of error as shown here. In case of success, is RECOMMENDED to return the 200 HTTP status code and the response body MAY be like the one shown in the following example.

An example of a query request and response follows:

Request

POST http://vaimee.org:8000/update

Headers

Content-Type: application/sparql-update
Accept: application/sparql-results+json

Body

PREFIX wot:<http://wot.arces.unibo.it/example#>
INSERT DATA {GRAPH <http://wot.arces.unibo.it/graph> {wot:Subject wot:Predicate "ვაიმეე"}}

Test the example with

Test the update example with the following

curl -X POST -d "PREFIX wot: <http://wot.arces.unibo.it/example#> INSERT DATA {GRAPH <http://wot.arces.unibo.it/graph> {wot:Subject wot:Predicate \"vaimee\"}}" -H "Content-Type: application/sparql-update" -H "Accept: application/sparql-results+json" http://localhost:8000/update

Headers

Content-Type: application/json

Body

{ "response" : {
    "isJsonBody": true,
    "body": {"ACustomJSONObject":"WithACustomSetOfMembers"}
}}

{ "response" : {
    "isJsonBody": false,
    "body": "A response string"
}}

Security

A SEPA implementation is RECOMMENDED to :

provide data encryption, server authentication and message integrity according to [[!RFC5246]]
support HTTPS [[!RFC2818]] and WSS [[!RFC6455]] protocols
be compliant with the security mechanism RECOMMENDED by the Web of Things interest group.

Registration

Registration allows a client to obtain the credentials needed to request (or renew) a JSON Web Token [[!RFC7519]]. Every SEPA implementation MUST support the client credentials authorization grant. Other authorization grants and registration mechanisms MAY be supported. To obtain the credentials, a client MUST own an application specific identifier, known as client_identity . The client_identity MAY correspond to the device serial number, the MAC address, the Electronic Product Code or any other sort of identifier defined by the application.

For the scope of this document, registration can be done once. Multiple registration requests (using the same client_identity ) are not allowed. Re-registration policies and mechanisms are out of the scope of this document.

An example of a client registration request and response follows:

Request

POST https://vaimee.org:8443/oauth/register

Headers

Content-Type: application/json 
Accept: application/json

Body

{ "register":{
    "client_identity":"68:a8:6d:1a:9c:04", 
    "grant_types":["client_credentials"]
}}

{"credentials":{
   "client_id":"5b60a155-bada-4499-bc6f-26b4d37bc1ef",
   "client_secret":"40e18d77-421c-48ce-a44a-14da1238e923",
   "signature":{
     "kty":"RSA",
     "e":"AQAB",
     "x5t":"...",
     "kid":"sepacertificate",
     "x5c":["..."],
     "n":"..."}}}

All SEPA implementations MUST support this JSON response. The JSON object contains the client credentials ( client_id and client_secret ) and the signature . The latter SHALL be used to verify the JWT on the client side.

In case of error, it is RECOMMENDED to reply as shown here.

Authentication

Once a client registered and holds the credentials, it can request a JWT by sending a request like the following:

Request

POST https://vaimee.org:8443/oauth/token

Headers

Content-Type: application/json
Accept: application/json
Authorization: Basic NWI2MGExNTUtYmFkYS00NDk5LWJjNmYtMjZiNGQzN2JjMWVmOjQwZTE4ZDc3LTQyMWMtNDhjZS1hNDRhLTE0ZGExMjM4ZTkyMw==

The authorization header uses the "basic" authentication scheme [[!RFC2617]] having as value the base64 encoding [[!RFC4648]] of the string "client_id:client_secret" (e.g., "5b60a155-bada-4499-bc6f-26b4d37bc1ef:40e18d77-421c-48ce-a44a-14da1238e923"). A SEPA broker implementation MUST respond to a token request with a JSON object like the following one:

			
{"token":{
  "access_token":"xabtQWoH8RJJk1FyKJ78J8h8i2PcWmAugfJ4J6nMd+1jVSoiipV4Pcv8bH+8wJLJ2yRaVage8/TzdZJiz2jdRP8bhkuNzFhGx6N1/1mgmvfKihLheMmcU0pLj5uKOYWFb+TB98n1IpNO4G69lia2YoR15LScBzibBPpmKWF+XAr5TeDDHDZQK4N3VBS/e3tFL/yOhkfC9Mw45s3mz83oyeoFFePUX8MQIuqd3TIcjOhoPgYWd0E+L/EN5wItL5/n78pX/8mVZcpxdyNNqr3bVvrCi0I84mIAefwQ0GyPxFhUHu9PtVNQnXchZuFgppX/YDtOesZSxfIoffUpHFPBY3u4FRIYwpSZX96Knnp0J22RQm+0l8yobik3z6jftw0jbF5+/YC6PnfZT3Wzb6PRJPuVkDzpo+BTC9eKx87GEj8VjtfXjbYRTeZNumD+59wL5kV/OrntNqNQD+IzAYoIZk4rlRbNouNnvT0laEhV012tSD1uAfNUxAlZjSbSMTp5bPNp7PoutMr5q6zPYfAC1PTKnVdkD1CDNqZnhB838WDeISfVzXsf7dsZ0+SkNPtx2kMUYCOYsxNJxyzza3lmaCuvxfnDT3g5F41/p/zX1tXYy6emVfdOWSkJNm1z0FJB/ZIUES0WAA5UEM3kejND++vvIQr38ar72HdFzRvP2V29CsaE5PMRRRZIE5ru9Zwgdb5lfMdwDi4sZkQdNRGHiOfRCT9D92mFVps6s6kv7HKojx05R9WKMDG8bEmSgMYSYQlQzLm93Ardw/hpDoB1/DfNRxbc/GVNZEVOoRVMye8/vICZtxvVeKmu4QawWKSBtrXelWUT8AHTG6v/c88pZjtJWDzy6YIIXLDQ2eJPu30mt3gLfS2ukIV4Tl5Oqu3T1IIghmNgek8vwWNeuG/JGeKrfUp6X6mMH9hdmj5+naOIr8V5rUKCjXnlWLAsrGdOvV8vuYYbx2IFQScZQJD/sTKj3gs6yeYpOwQ2iEs9asA=",
  "token_type":"Bearer",
  "expires_in":3600
}}

The JSON response MUST contain the following keys: access_token is the JWT, token_type to specify the token type (i.e., the default is bearer ) and expires_in as the number of seconds after which the token will expire. Once a token is expired, the client can request a new token by using its credentials. Requesting a token while the current one is not expired generates an error.

In case of error, it is RECOMMENDED to reply as shown here.

Secure access

HTTPS requests (e.g., https://vaimee.org:8443/secure/update) MUST include the authorization header as shown in the following example:

Authorization: Bearer xabtQWoH8RJJk1FyKJ78J8h8i2PcWmAugfJ4J6nMd+1jVSoiipV4Pcv8bH+8wJLJ2yRaVage8/TzdZJiz2jdRP8bhkuNzFhGx6N1/1mgmvfKihLheMmcU0pLj5uKOYWFb+TB98n1IpNO4G69lia2YoR15LScBzibBPpmKWF+XAr5TeDDHDZQK4N3VBS/e3tFL/yOhkfC9Mw45s3mz83oyeoFFePUX8MQIuqd3TIcjOhoPgYWd0E+L/EN5wItL5/n78pX/8mVZcpxdyNNqr3bVvrCi0I84mIAefwQ0GyPxFhUHu9PtVNQnXchZuFgppX/YDtOesZSxfIoffUpHFPBY3u4FRIYwpSZX96Knnp0J22RQm+0l8yobik3z6jftw0jbF5+/YC6PnfZT3Wzb6PRJPuVkDzpo+BTC9eKx87GEj8VjtfXjbYRTeZNumD+59wL5kV/OrntNqNQD+IzAYoIZk4rlRbNouNnvT0laEhV012tSD1uAfNUxAlZjSbSMTp5bPNp7PoutMr5q6zPYfAC1PTKnVdkD1CDNqZnhB838WDeISfVzXsf7dsZ0+SkNPtx2kMUYCOYsxNJxyzza3lmaCuvxfnDT3g5F41/p/zX1tXYy6emVfdOWSkJNm1z0FJB/ZIUES0WAA5UEM3kejND++vvIQr38ar72HdFzRvP2V29CsaE5PMRRRZIE5ru9Zwgdb5lfMdwDi4sZkQdNRGHiOfRCT9D92mFVps6s6kv7HKojx05R9WKMDG8bEmSgMYSYQlQzLm93Ardw/hpDoB1/DfNRxbc/GVNZEVOoRVMye8/vICZtxvVeKmu4QawWKSBtrXelWUT8AHTG6v/c88pZjtJWDzy6YIIXLDQ2eJPu30mt3gLfS2ukIV4Tl5Oqu3T1IIghmNgek8vwWNeuG/JGeKrfUp6X6mMH9hdmj5+naOIr8V5rUKCjXnlWLAsrGdOvV8vuYYbx2IFQScZQJD/sTKj3gs6yeYpOwQ2iEs9asA=

WSS requests (e.g., wss://vaimee.org:9443/secure/subscribe) MUST include the authorization member as described in the SPARQL 1.1 Subscribe document.

In case of error, it is RECOMMENDED to reply as shown here.

Error responses

In case of error, a SEPA broker implementation SHOULD reply with a JSON object like the following:

 {
   "error" : "unauthorized_client",
   "error_description" : "Client is not authorized",
   "status_code" : 401
 }

The error member is a string representing the error. Refer to [[!RFC6749]] for all OAuth related errors. Otherwise it would be a SPARQL 1.1 SE Protocol specific error string.

The error_description member is optional and if present it provides a human readable description of the error.

The status_code member is an integer representing the error. The use of use of HTTP status codes [[!RFC2616]] is RECOMMENDED. As reference, a list of common HTTP status codes follows. Implementation specific error codes MAY also be used.

400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Request Entity Too Large
414 Request-URI Too Long
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported

Introduction

Document conventions

Terminology

SPARQL 1.1 Query

SPARQL 1.1 Update

SPARQL 1.1 Subscribe

Security

Registration

Authentication

Secure access

Error responses

Acknowledgements