Contract No.: 285248 Strategic Objective

Download 1.78 Mb.

Page	47/54
Date	28.01.2017
Size	1.78 Mb.
	#8871

1 ... 43 44 45 46 47 48 49 50 ... 54

23.13Content Based Security Glossary

Broker: the component that generates keys to remove protection from data
Consumer: the component that removes protection from data
Content Based Security: the concept of protecting data and its metadata at its source and integrating access control in a managed way
Metadata: labels describing data content
Provider: the component that applies protection to data

23.13.1Acronyms

CBS Content Based Security
JKS Java KeyStore
OGE Optional Generic Enabler
SSL Secure Sockets Layer
WAR Web Archive

24FIWARE OpenSpecification Security Optional Security Enablers ContentBasedSecurity Open RESTful API Specification

24.1.1Introduction to the Content Based Security GE API

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

Content Based Security API Core

The Content Based Security (CBS) API provides services that encrypt, decrypt, sign and verify data. It is a RESTful API accessed via HTTP that uses XML-based and JSON-based representations for information interchange. Note that data to be protected need not be either XML or JSON.

Intended Audience

This specification is intended for software developers and reimplementers of this API. For the former, this document provides a full specification of how to interoperate with the Content Based Security API to encrypt, sign, decrypt and/or verify data. For the latter, this specification describes the interface to be provided to allow clients to interoperate with the Content Based Security.

In order to use this specification, the reader should first have a general understanding of the Content Based Security Optional Generic Enabler supporting the API.

Throughout this specification it is assumed that the reader is familiar with:

RESTful web services
HTTP/1.1
XML and JSON data serialization formats.

API Change History

Current version is: Version 1.0.0, 15/4/2013

This version of the Content Based Security API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date	Changes Summary
Apr 19, 2013	Version 1 of the Content Based Security GE API Guide.

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see FIWARE.ArchitectureDescription.Security.Optional Security Enablers.ContentBasedSecurity

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at FIWARE.OpenSpecification.Security.Optional Security Enablers.ContentBasedSecurity.Open RESTful API Specification. For more details about the Content Based Security Service that this API is based upon, please refer to FIWARE.ArchitectureDescription.Security.Optional Security Enablers.ContentBasedSecurity.

24.1.2General CBS API Information

Resources Summary

The mapping of CBS functionality to a resource tree is shown in the figure below.

cbs api resource tree

Authentication

Users authenticate using Basic or Digest authentication prior to accessing the service.

Representation Format

The Content Based Security API supports the transmission of XML and JSON documents. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of the wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Limits

Limits are not yet specified for Version 1 of the Content Based Security GE.

Versions

Querying the version is not supported in Version 1 of the Content Based Security GE.

Extensions

Querying extensions is not supported in Version 1 of the Content Based Security GE.

Faults

Fault Element	Associated Error Codes	Expected in All Requests?	Description
Bad Request	400	Yes	The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
Unauthorised	401	Yes	Client authentication is required.
Forbidden	403	Yes	The request was a valid request and the server understood it, but is refusing to fulfil it, e.g. because the rule set installed in the server does not permit the request.
Not Found	404	Yes	The request specified a URI of a resource that does not exist.
Method Not Allowed	405	Yes	The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
Not Acceptable	406	Yes	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
Internal Server Error	500	Yes	The server encountered an unexpected condition which prevented it from fulfilling the request.
Not Implemented	501	Yes	The server does not (currently) support the functionality required to fulfil the request.
Service Unavailable	503	Yes	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

24.1.3Data Types

This subsection describes the data structures used in the Content Based Security API.

Type: UnprotectedContainer

A data type representing an unprotected data container (i.e. before encryption and/or signing have been applied).

Name	Type	Required	Description
mode	text	true	The data protection mode to be applied to the protected representation of this container. Possible values are: ENCRYPT SIGN SIGN_THEN_ENCRYPT ENCRYPT_THEN_SIGN
headers	keyValue [0..*]	false	A collection of keyValue entries representing headers to be included in the container. If there are no header entries, this may be omitted. In some cases a particular implementation or deployment may require particular header entries to be present, e.g. the mime-type of the data. The difference between container headers and container metadata is that metadata is included as input to the container key generation algorithm, while headers are not.
metadata	keyValue [0..*]	false	A collection of keyValue entries representing metadata to be included in the container. If there are no metadata entries, this may be omitted. In some cases a particular implementation or deployment may require particular metadata entries to be present. The difference between container headers and container metadata is that metadata is included as input to the container key generation algorithm, while headers are not.
payload	base64 encoded binary	true	The data (plaintext) to which the specified protection mode will be applied to the protected representation of this container.

Type: ProtectedContainer

A data type representing a protected container (i.e. after encrypting and/or signing).

Name	Type	Required	Description
protectedContainer	base64 encoded binary	true	This is the protected data returned to the user. The protected data is returned in a base64 encoded container.

Type: KeyValue

The KeyValue type is used in container headers and metadata to map a key to a value. The key name is used as the element name, while the value is the element content.

Name	Type	Required	Description
key	text	true	Key with which the specified value is to be associated
value	text	true	Value to be associated with the specified key

24.1.4API Operations

In this section we describe each operation in depth. The operations are divided into two functions: CBS Producer and CBS Consumer. The CBS Producer functionality performs encryption and/or signs the provided data. The CBS Consumer decrypts and/or verifies the signature on the provided container.

CBS Producer

Request

POST //{serverRoot}/fiware.cbs.producer.service.webapp/api/cbss/protect

Request Parameters

None.

Request Body

A representation of the unprotected container to which the CBSS will apply protection.

Response

200 OK – The request was successful. The response body contains a representation of the protected container.

403 Forbidden - The user was not authorised to protect the data

Example Request

XML request:

POST /api/cbss/protect HTTP/1.1

Accept: application/xml

Content-type: application/xml

SIGN_THEN_ENCRYPT

value

...

value

...

TWFuIGlzIGRpc3Rpbmd1a...

JSON request:

POST /api/cbss/protect HTTP/1.1

Accept: application/json

Content-type: application/json

{

"mode":"SIGN_THEN_ENCRYPT",

"headers":{

"key":"value",

...

},

"metadata":{

"key":"value",

...

"payload":"TWFuIGlzIGRpc3Rpbmd1a..."

}

Example Response (Success)

XML response:

HTTP/1.1 200 OK

Content-Type: application/xml

dWVkIGFuZCBpbmRlZmF0aWdhY...

JSON response:

HTTP/1.1 200 OK

Content-Type: application/json

{

"protectedContainer":" dWVkIGFuZCBpbmRlZmF0aWdhY..."

}

Example Response (Failure)

If the installed rule set does not permit the client to make the request, the following response will be returned:

HTTP/1.1 403 Forbidden

Encrypt failed (not authorised).

CBS Consumer

Request

POST //{serverRoot}/fiware.cbs.consumer.service.webapp/api/cbss/unprotect

Request Parameters

None.

Request Body

A representation of the protected container from which the CBSS will remove protection.

Response

200 OK – The request was successful. The response body contains a representation of the unprotected container.

400 Bad Request - The signature verification failed.

403 Forbidden - The user was not authorised to remove protection from the data.

Example Request

XML request:

POST /api/cbss/unprotect

Accept: application/xml

Content-Type: application/xml

dWVkIGFuZCBpbmRlZmF0aWdhY...

JSON request:

POST /api/cbss/unprotect HTTP/1.1

Accept: application/json

Content-type: application/json

{

"protectedContainer":" dWVkIGFuZCBpbmRlZmF0aWdhY..."

}

Example Response (Success)

XML response:

HTTP/1.1 200 OK

Content-Type: application/xml

SIGN_THEN_ENCRYPT

value

...

value

...

TWFuIGlzIGRpc3Rpbmd1a...

JSON response:

HTTP/1.1 200 OK

Content-Type: application/json

{

"mode":"SIGN_THEN_ENCRYPT",

"headers":{

"key":"value",

...

},

"metadata":{

"key":"value",

...

"payload":"TWFuIGlzIGRpc3Rpbmd1a..."

}

Example Response (Failure)

If the installed rule set does not permit the client to make the request, the following response will be returned:

HTTP/1.1 403 Forbidden

Decrypt failed (not authorised).

If the signature verification failed, the following response will be returned:

HTTP/1.1 400 Bad request

Signature verification failed.

Download 1.78 Mb.

Share with your friends:

1 ... 43 44 45 46 47 48 49 50 ... 54