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
FIWARE.OpenSpecification.Security.Privacy - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.Privacy

From FIWARE Forge Wiki

Jump to: navigation, search
Name FIWARE.OpenSpecification.Security.Privacy
Chapter Security,
Catalogue-Link to Implementation Privacy
Owner Zürcher Hochschule der Angewandten Wissenschaften, Stephan Neuhaus (ZHAW)

Contents

Preface

Within this document you find a self-contained open specification of a FIWARE generic enabler, please consult as well the FIWARE Product Vision, the website on http://www.fiware.org and similar pages in order to understand the complete context of the FIWARE platform.

Copyright

Copyright © 2014-2015 Zürcher Hochschule der Angewandten Wissenschaften.

Legal Notice

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

Overview

The goal of the Privacy GE is to support Privacy-Preserving Attribute-Based Credentials (P2ABC). These allow people to prove something about themselves (for example that they are older than 18, or that the name on their concert ticket is the same as the name on their passport), but at the same time revealing only the smallest amount of personally identifying information (in this case their actual date of birth or their names or passport numbers).

P2ABC are realised through multi-round protocols that require exchanging many artifacts and requires logic for crypto. In our architecture, we have three actors, realised by three services:

  • The user service that runs on the end-user's machine. The user service talks to the two other services. The functionality provided by the user-service could also be implemented as browser plugins and/or possibly as a pure JavaScript library, but our reference implementation consists of the RESTful user service and the user UI service.
  • The verification service. That service will demand attributes or predicates and will check that the provided attributes or predicates are indeed genuine and/or true.
  • The issuance service that is responsible for communicating with identity sources and attribute sources and for issuing the credentials. This service uses an identity source to authenticate users and an attribute source to retrieve the users' attributes to embed into credentials.

All services have associated UI services. For the issuer and verifier, these configure the services with data that can or should not be in the deployment descriptors. For the user service, the UI service as written is a very rudimentary GUI that exposes all the functions of the user service. It must be emphasised that it is well possible, by writing a suitable UI service, to hide most of the complexities of the user service from the user so that his or her user experience is very much like using ordinary credentials. In fact, once a credential is obtained, no additional authentication step is technically necessary, so using P2ABC may actually be more pleasant to use than ordinary ones.

It should also be emphasised that an end user is not physically required for an interaction. If it is desired to protect data with privacy-preserving credentials when services are talking to each other without any user interaction, all that is needed is to install the user service alongside the service that requests the resources, and provide the user service with the necessary identity information in its configuration. Of course, then the requesting service will have to talk to the user service using the exposed API, and there would have to be one instance of the user service for every user for which the service requests resources. This is due to the single-tenant nature of the user service.

Overview
Overview of the three involved services of P2ABC.
Verification flow, part 1
Verification flow, first part. In this part, the user requests a resource. As a consequence, provides the necessary presentation token, and is issued with a redirection URL.
Verification flow, part 2
Verification flow, second part. In this part, the user follows the redirection URL that it has received from the verifier. The resource owner checks the access token and, if successful, serves the resource. Please note that an end user will use the user service to talk to the verification service first and only comes into contact with the actual resource after the verification succeeded. This means that a resource CAN NOT provide a login page or a page that redirects the user to a login page because the verification flow runs through the user service.

Basic Concepts

The concepts themselves are described and defined in the glossary. In this section, we see how the concepts interact.

In this section, we will use the following scenario as an example. Consider a video streaming service WebFilms that only issues flat rates. Therefore, in order to start streaming a movie, it is only relevant to WebFilms that the user has a valid subscription. In particular, the user's name and address are irrelevant. The only other thing that WebFilms cares about is that it must not stream films to people who are below the required age. But even then, it is only relevant that the user's date of birth is before a certain date; the actual date of birth is still irrelevant.

Let's say that Alice, based in the UK, wants to watch the movie Licence to Kill from WebFilms. This is a blow-by-blow account of what happens with privacy-preserving credentials.

  1. Alice, a user, signs up for WebFilms by making her user service contact the issuer part of WebFilms to obtain a credential. This is the part where Alice gives WebFilms all the data they need for age verification and billing, such as her date of birth, address, and credit card information.
  2. Alice then selects a movie and makes her user service contact the verifier part of WebFilms to ask it for a presentation policy. Alice in effect asks "what information do you need from me before streaming the movie?".
  3. The verifier part of NetFilms checks its database, sees that Licence to Kill has the BBFC's 15 certificate, and thus answers with an appropriate presentation policy. This policy contains a formalised version of the statement "For this movie, I need you to prove to me that you are older than fifteen, and I need you to do that with credentials that have been issued by WebFilms".
  4. Alice's user service checks her credentials and sees that she has one from NetFilms. P2ABCs allow her to prove to NetFilms that she is a current subscriber and older than 15 without revealing either her name, customer number, date of birth or indeed any other personally identifiable information. The result of this proof is a presentation token, which Alice's user service sends to the verifier.
  5. The verifier receives Alice's presentation token, checks it and, because the check is successful, concludes that she must be a subscriber and older than fifteen. So he sends redirection URI, which is a link to access the movie. That link contains an embedded token that is used in Step 7.
  6. Alice's user service causes her browser to be redirected to the redirection URI, which points to a resource owned by the resource owner.
  7. The resource owner receives the request, extracts the token, and verifies it with the verifier. The token is genuine, so the resource owner can finally start to stream Licence to Kill.

Please note the following:

  • Alice's user experience is not different from any other service. In fact, it might be even simpler since she will only be presented with a box saying that "WebFilms wants to know that you are older than 15", but doesn't have to remember usernames or passwords.
  • The resource owner's programming is similarly almost unaffected. Except for checking the token, nothing changes; and checking the token can be done in a few lines of Java (see the example below). We will also provide a Servlet filter so that resources can be protected without changing the resource owner's programming at all.
  • Alice has not revealed any personally identifiable information. WebFilms won't know who they are streaming the film to.
  • Despite that, WebFilms know that the person who has authenticated with P2ABC is (a) a subscriber and (b) older than fifteen. (Whether Alice's little sister Eve has simply obtained access to Alice's credentials is of course another matter. We assume that, once Alice gets the monthly list of streamed films, there will be some discord among the siblings.)
  • In this example, the issuer, verifier, and resource owner were all essentially the same organisation, but that is of course not necessary. However, the resource owner must trust the verifier, and the verifier must believe that the issuer's credentials contain correct attributes.
 @GET()
 @Path("/page/")
 public Response resource(@QueryParam("accesstoken") String accessToken)
         throws Exception {
     try {
         String result = (String) RESTHelper
                 .getRequest("http://your-verifier.your-company.com/zhaw-p2abc-webservices/verification/verifyAccessToken?accesstoken="
                         + URLEncoder.encode(accessToken, "UTF-8")); //performs a HTTP-GET request
 
         if (result.equals("resource")) {
             // Your response goes here
             return Response.ok("You are allowed to access this page: " + result)
                     .build();
         } else {
             return Response.status(Response.Status.FORBIDDEN)
                     .entity("You are not allowed to access this page: " + result).build();
         }
     } catch (Exception e) {
         return Response.status(Response.Status.FORBIDDEN)
                 .entity("You are not allowed to access this page!").build();
     }
 }

Trust Issues

  • The user trusts the issuer to keep its attributes safe and to issue only valid credentials in its name.
  • The verifier trusts the issuer to issue only valid credentials.
  • The resource owner trusts the verifier to correctly verify access tokens.

Note however that the verifier need not trust the user and that the issuer and verifier cannot collude to unmask a user's identity if no identifying information was requested in the presentation policy.

Main Interactions

Issuance Service

Issuers need to host an instance of the Issuance Service. Issuers are responsible for creating the System Parameters and making them available, and also for creating the Issuer Parameters and Credential Specifications. The issuer knows all the User's attributes and therefore the user IS NOT ANONYMOUS for the issuer during an issuance protocol.

The issuance service must be configured to use at least one identity source and at least one attribute source. Examples of such sources are LDAP directories or JDBC-compatible relational databases. The issuance-service is capable of performing authentication of users through LDAP and SQL-Databases as well as read attributes of users from either LDAP or an SQL-Database (through JDBC). It is capable of generating credential specification based on meta-information provided by the attribute source (i.e. it can generate credential specifications for attributes in an SQL Table or an object class in LDAP).

One special identity source is IdM. We support IdM as an identity source, but since IdM does not support additional attributes, it is unavailable as an attribute source.

Verification Service

Verifiers need to host an instance of the Verification Service. It is not necessary for a resource owner to be a verifier but a resource owner can also be a verifier. The verifier is responsible for managing resources (from resource owners), presentation policies and access tokens. The verifier is able to verify the credentials of a user against a presentation policy.

The purpose of the verification service is to protect access to resources with P2ABC. It acts like a PDP. Resources can be registered with the verification service by giving it:

This latter URI is used to redirect the user's browser after the user's credentials are successfully verified. The verification service will generate access tokens that resource owners can use to check if a user has successfully completed the verification. A resource owner can of course run his own verification service; or he could rely on someone else's. Of course, a resource owner can actually also run his own issuance service.

This means that the resource owner must TRUST the verifier.

User Service

The user service—simply put—provides the required client side logic of P2ABC through a REST-API. Unlike the other services, this service runs on the end user's machine, in parallel to the user's browser. This reference implementation is implemented in Java. Alongside the user service is a user UI service. In our reference implementation, this exposes the entire user service's API and involves the user in every step, but it is entirely possible to write a UI service that hides most of these steps from the user.

Users can request credentials from issuers and use them to request access to a resource at verifiers. The verifier will grant the user an access token which the user can give the resource and then the resource can verify the access token through the verifier.

Obtain credential (GUI)
A picture of the GUI for the user-service. This picture shows the form to obtain a credential from an issuer.

Please be aware that communication in a verification flow and issuance flow will run through the user-service. This means that to authenticate to a third-party website (using a verifier) the user will open the GUI for his user-service and enter his credentials/details and the URL of the verifier. To get access to a resource the user can not directly go to that resource but has to contact a verifier first through the user-service.

Basic Design Principles

  • Each entity in the interactions diagram should get its own service.

Additional Information

We are planning to use the Privacy GE together with the Web UI GE in the context of smart cities. In this case, smart cities would allow citizens (but only those) to leave comments during a virtual tour of the city. Comments could then only be made by genuine citizens (as proved by possession of an appropriate credential), but without the citizens revealing their identity.

Detailed Specifications

Following is a list of Open API Specifications linked to this Generic Enabler. These Specifications are presently delivered directly on the APIARY platform which is followed from the API Blueprint process recommendations.

Open API Specifications

The Privacy API Open Specification can be found at the following link:

http://http://docs.privacygep2abcapiopenspecification.apiary.io

Re-utilised Technologies/Specifications

Terms and definitions

This section comprises a summary of terms and definitions introduced during the previous sections. It intends to establish a vocabulary that will be help to carry out discussions internally and with third parties (e.g., Use Case projects in the EU FP7 Future Internet PPP). For a summary of terms and definitions managed at overall FIWARE level, please refer to FIWARE Global Terms and Definitions

NOTE: this glossary is referred to from other documents as well and will therefore contain definitions for terms that do not appear in this document.

Access Token

An access token is a token that the #User Service obtains from a #Verifier and then presents to the #Resource Owner to prove that he has successfully verified his credentials. Before granting access to the resource, the resource owner should check the validity of the token with that same #Verifier.

Authentication Provider

An authentication provider is a class extending ch.zhaw.ficore.p2abc.services.issuance.AuthenticationProvider. The purpose of that class is to implement an #Identity Source.

Attribute Provider

An attribute provider is a pair of classes extending ch.zhaw.ficore.p2abc.services.issuance.AttributeInfoProvider and ch.zhaw.ficore.p2abc.services.issuance.AttributeValueProvider, respectively. The purpose of these classes is to implement an #Attribute Source.

Attribute Source

An attribute source is a data source that provides a mapping from a name to a set of attributes. For example, a personnel table in a SQL database could map an employee's name to a set of attributes containing date of birth, sex, and monthly salary. The data in an attribute source is split into two parts. The first part is the meta-data, which contains the names and types of the attributes. In our example above, this could be dob with the type date, sex with type string and salary with type nonnegative number with two decimal places after the decimal point.

Credential

A credential is a set of #Attributes that have been vouched for by an #Issuer. For example, the President of the United States's passport is a credential which among others contains the name/value pair ("name", "Barack Obama"). In #P2ABC, the #Issuer vouches for the attributes by (a) having access to a trusted #Attribute Source and (b) having access to a trusted #Identity Source. When a #User successfully authenticates with the #Identity Source, the #Issuer will believe that the #User is authentic and will issue credentials with attributes taken from the #Attribute Source.

Identity Source

An identity source is a data source that can be used to authenticate users. Typical identity sources are LDAP and SQL databases.

Issuance Service

The issuance service is a web service that issues #P2ABC. It needs access to an #Identity Source to authenticate users, and to an #Attribute Source for the attributes to put into a credential.

Issuance Policy

An issuance policy described what kinds of attributes the credentials that conform to it will contain. For example, WebFilms's credentials could contain the user's date of birth, so the issuance policy would say "credentials contain an attribute called dob, which is of type date".

P2ABC

A shorthand notation for Privacy-Preserving Attribute-Based Credentials

Presentation Policy

In the most general sense, a presentation policy is a list of attributes or predicates that the #Verification Service will want revealed or proved before granting access to a resource. As an example, consider WebFilms, who demand that you reveal that you have a valid subscription from them, but for age-restricted movies only need you to reveal that your date of birth is before a certain cut-off date. Their presentation policy could therefore essentially say "If you want to stream this movie, you must reveal to me that your date of birth is before 1998-02-02, as issued in a credential by WebFilms".

Redirect URI

A redirect URI is an URI to which the user's browser will be redirected after successfully completing credential verification. This is necessary because credential verification is a protocol where messages are exchanged between the user service and the verification service in multiple rounds, unlike the simplistic HTTP request/response protocol. This URI is generated by the verifier using information that the #Resource Owner provided when registering the resource. It also contains an #Access Token.

Resource Owner

The resource owner wants to serve resources, but at the same time wants to protect them with #P2ABC.

User

A user is a person operating a browser and wishing to access resources that are protected by #P2ABC. In our reference implementation, the user (or the user's browser) does not interact directly with the issuer and verifier, but instead uses the #User Service, a web service running on the user's computer. It is possible in principle to replace that web service with JavaScript.

User Service

The user service is a web service that runs on the same machine as the #User's browser. It communicates with the #Issuance Service to obtain credentials, with the #Verification Service to obtain presentation policies, present presentation tokens, and obtain access tokens, and with the #Resource Owner to obtain access to a resource. As such, it is more an artifact of our reference implementation than a necessity.

Verification Service

The verification service is a web service that verifies #P2ABC according to a #Presentation Policy. The result of a successful verification is a #Redirect URI containing an #Access Token.

Personal tools
Create a book