We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Secure Storage Service Optional GE Open API Specification - FIWARE Forge Wiki

Secure Storage Service Optional GE Open API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Copyright

Copyright © 2012-2013 by Thales

Legal notice

Please check the following Legal Notice to understand the rights to use these specifications.

Introduction to the Secure Service Storage Optional GE API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.


Overview

The Secure Storage Service provides a storage for labelled (i.e. XML-DSig protected) data. It comes with an application-level filter which authorizes read access in function of the identity of the authenticated requester (for example, a service provider) and in function of the sensitivity of the data.

File:Overview_sss.jpg


Basic Concepts

XML-DSig (for XML Digital Signature) defines an XML syntax for digital signatures and is defined in the WC3 recommendation XML Signature Syntax and Processing. Functionally, it has much in common with PKCS#7 but is more extensible and geared towards signing XML documents. XML signatures can be used to sign data –a resource– of any type, typically XML documents, but anything that is accessible via a URL can be signed. An XML signature used to sign a resource outside its containing XML document is called a detached signature; if it is used to sign some part of its containing document, it is called an enveloped signature; if it contains the signed data within itself it is called an enveloping signature.


The data is labelled before being stored, i.e. it is previously protected by its owner. Moreover, the owner himself has initialised the sensitivity level of the different fields of his data (for example : mail address > private, main interest > public, job > public, etc...). Once the data are stored by SSS, the public fields (i.e. the fields that have been tagged 'public') can be read by anyone. The private one can be read by trusted service providers (SP) only. A trusted service is a service which is authenticated by a certificate which has been delivered by a dedicated Certification Authority.


Intended Audience

This specification is intended for Service Consumers (with development skills) and Users. For the Service Consumers, this document provides a full specification of how to interoperate with the Secure Storage Service API. For the latter, this specification indicates the interface to be provided to the client application developers to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Optional Generic Enabler service Secure Storage . The API user should be familiar with:

  • RESTful web services
  • HTTP/1.1
  • XML data serialisation formats.

API Change History

Current version is: Version 1.1.0, 27/05/2013

The most recent changes are described in the table below:

Revision Date Changes Summary
May 27, 2013
  • Version 1.1 of the Secure Storage Service Optional GE API Guide.

Additional Resources

More documentation related to the architecture is available at Secure Storage Service

General SSS API Information

SSS Optional GE API Core

  1. CreateUser(Credentials) is a RESTful method accessed via HTTPs that creates a user in the database. The method takes one parameter, the credentials.
  2. DeleteUser(Credentials, userID) is a RESTful method accessed via HTTPs that deletes a user on the SSS. The method takes two parameters; one for the credentials, and the second for the user ID.
  3. AddUserData(Credentials, userID, XML data) is a RESTful method accessed via HTTPs that stores files in a user storage. The method takes three parameters; one for the credentials the second for the user ID and the third for the file added in the user storage.
  4. UpdateUserData(Credentials, userID, UniqueID, File) is a RESTful method accessed via HTTPs that updates a user in the database. The method takes four parameters; one for the credentials, the second for the user ID, the third for the file UniqueId, the fourth for the new File.
  5. GetUserData(Credentials, userID, FilesList) is a RESTful method accessed via HTTPs that retrieves files in a user storage. The method takes three parameters; one for the credentials, the second for the user ID and the third for the files listed by their UniqueIDs in the FilesList.
  6. DeleteUserData(Credentials, userID, FilesList) is a RESTful method accessed via HTTPs that deletes files in a user storage. The method takes three parameters; one for the credentials, the second for the user ID and the third for the files listed by their UniqueIDs in the FilesList.
  7. AddUserServices(Credentials, userID, ServicesList) is a RESTful method accessed via HTTPs that adds new user’s registered services. The method takes three parameters; one for the credentials, the second for the user ID and the third for the list of new services associated to the UniqueIDs.
  8. GetUserServiceList(Credentials, userID) is a RESTful method accessed via HTTPs that retrieves the list of SPs which the user has subscribed to. The method takes two parameters; one for the credentials, and the second for the user ID.
  9. ActivateProfile(Credentials, userID, boolean) is a RESTful method accessed via HTTPs that (de)activates a profile. The method takes three parameters; one for the credentials, the second for the user ID and the third for the Boolean specifying whether the profile is (de)activated.


Representation Format

The Secure Storage Service Optional GE API supports the transmission of XML files and Strings. Content-Type header and is required for operations that have a request body. The response format is always in plain text ("text/plain") or ("application/xml").

In order to manipulate the different XML elements of the SSS within the application, XML representations using JAXB (Java Annotation Xml Binding, see http://jaxb.java.net/ for more information) were used.


Representation Transport

Resource representation is transmitted between client and server by using HTTPs 1.1 protocol. Both client and server may use as many HTTP headers as they consider necessary.


API Operations

In this section we go in depth for each operation.


Glossary

Credentials: X509 Digital certificate or login/password to authenticate the User or SP

SP: Service Provider

SPID: Unique ID associated to each SP


Operations

Verb URI Description
POST /createUser/{Credentials} Creates a new user in the SSS database.
POST /deleteUser/{Crendentials}/{userID} Deletes an existing user.
POST /addUserData/{Crendentials}/{userID}/{XML File} Adds data (XML File) associated to the User in the SSS.
POST /updateUserData/{Crendentials}/{userID}/{UniqueID}/{XML File} Updates data (XML File) identified by the given UniqueID.
GET /getUserData/{Crendentials}/{userID}/{FilesList} Gets data (a list of XML File) identified by the given FilesList (list of UniqueIDs).
POST /deleteUserData/{Crendentials}/{userID}/{FilesList} Deletes data (a list of XML File) identified by the given FilesList (list of UniqueIDs).
POST /addUserServices/{Credentials}/{userID}/{ServicesList} Add SPs authorized to access Files (SP IDs associated to Unique IDs).
GET /getUserServicesList/{Credentials}/{userID} Retrieve a list of SPs authorized to access data from a User.
POST /ActivateProfile/{Credentials}/{userID}/{boolean} (De)activate a user if needed.


Create a User identified by his Credentials

/sss
POST
Parameter:
Content:
plain/text
Return:
plain/text
userID
String
{"uniqueId" : uid }
password
String
Creates the User entry in the table identified by the given UserId and Password.
Return
201
User successfully created
500
User not created, an error occured


Delete a User identified by his Credentials

/sss
POST
Parameter:
userId, password
Content:
Return:
plain/text
Deletes a user identified by the given UserId and Password.
Return
200
If User found
404
If User not found


Store a file (XML) associated to its user

/sss
POST
Parameter:
Content:
application/xml
Return:
plain/text
file
File
{"uniqueId" : uid }
owner
String
Stores an XML file
Return
201
File successfully stored
500
File not stored, an error occured


Update a File identified by the its UniqueId and UserID

/sss
POST
Parameter:
Content:
application/xml
Return:
plain/text
uniqueId
Long
{"uniqueId" : uid }
file
File
userID
String
Updates an XML File identified by the given UniqueId and UserID
Return
200
File successfully updated
500
File not updated, an error occured
404
File not found


Delete a File identified by its UniqueId and UserId

/sss/deleteUserData
POST
Parameter:
Content:
application/json
Return:
application/json
uniqueId
Long
{“deleted” : boolean}
userID
String
Delete a File identified by theUniqueId and UserID
Return
200
See response body

|}

Personal tools
Create a book