This document describes the SPARQL 1.1 Secure Event (SE) Protocol that MUST be implemented by a generic SPARQL SE Service.
This is a first draft.

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:

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 :

An example of a query request and response follows:

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:

SPARQL 1.1 Subscribe

A SEPA broker implementation is RECOMMENDED to use Websockets [[!RFC6455]] as protocol for the subscription mechanism. Subscribe/unsubscribe requests and notification are expressed according to the SPARQL 1.1 Subscribe language.

Security

A SEPA implementation is RECOMMENDED to :

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:

{"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:

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://mml.arces.unibo.it: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://mml.arces.unibo.it: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
	

Acknowledgements

Editors would like to thanks the Advanced Research Center on Electronic Systems "Ercole De Castro" (ARCES) and the Computer Science and Engineering Department (DISI) of the University of Bologna, the European Commission and all the partners of the ARTEMIS projects who inspired the SPARQL Event Processing Architecture (SEPA).