Technical Standards
iSHARE can be described as an API architecture, which enables all parties involved to engage in direct communication. For interoperability reasons, iSHARE makes use of widely used open standards. Modified implementations of OAuth 2.0 and OpenID Connect 1.0 are used to facilitate an ecosystem in which parties can interact with previously unknown parties. Pre-registration, therefore, is not a prerequisite and this requires alterations to the official standards. Also, for the authentication of parties within an iSHARE context, iSHARE uses PKI and digital certificates relating to all participating parties.
API
An API (Application Programming Interface) is a technical interface, consisting of a set of protocols and data structuring standards (‘API specifications’) which enables computer systems to directly communicate with each other. Data or services can be directly requested from a server by adhering to the protocols. APIs are used to hide the full complexity of software and make it easy for third parties to use parts of software or data services. APIs are mainly meant for developers to make the creation of new applications depending on other applications easier.
APIs are used in iSHARE to facilitate direct and realtime communication between different parties, eliminating the need for a central platform. iSHARE APIs are designed to be RESTful, and JSON is used for structuring data. iSHARE prescribes caching requirements relating to the use of APIs in various situations.
Caching
Caching is a way to boost performance efficiency. Often data is temporarily stored on a different medium, to enable faster access to the data.
For every API exposed under iSHARE caching MUST Be made explicit to the API consumer.
If a response is not cacheable it MUST contain the following headers:
If a response is cacheable it MUST contain the following headers:
Note
max-age MAY vary
HTTP(S)
HyperText Transfer Protocol (Secure) is a communication protocol. iSHARE Scheme communication MUST be carried out over the HTTP protocol, and secured through TLS 1.2 resulting in HTTPS.
iSHARE authentication/authorisation data is generally transferred in HTTP Headers. These headers can become very large when containing multiple encrypted certificates or JWT’s. iSHARE parties SHOULD configure their web servers to accept HTTP headers of larger sizes (usually 10K or more) to minimise implementation impact on current services.
The most recent version of the HTTP specification can be found at w3.org.
After sending a HTTP request to a server, the server responds with (among others) a Status Code which indicates the outcome of the request made to the server.
HTTPverb | CRUD | Entire Collection (e.g. /parties) | Specific Item (e.g. /parties/{id}) |
POST | Create | 201 (Created), ‘Location’ header with link to /customers/{id}containing new ID. | 404 (Not Found), 409 (Conflict) if resource already exists. |
GET | Read | 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. | 200 (OK), single customer. 404 (Not Found) if not found or invalid. |
PUT | Update Replace | 404 (Not Found), unless you want to update/replace every resource in the entire collection. | 200 (OK) or 204 (No Content). 404 (Not Found) if not found or invalid. |
PATCH | Update Modify | 404 (Not Found), unless you want to modify the collection itself. | 200 (OK) or 204 (No Content). 404 (Not Found) if not found or invalid. |
DELETE | Delete | 404 (Not Found), unless you want to delete the whole collection,not often desirable. | 200 (OK). 404 (Not Found) if not found or invalid. |
JSON
JSON (JavaScript Object Notation) is a data formatting standard. JSON is an open standard data format that does not depend on a specific programming language. This compact data format makes use of human-readable (easy to read) text to exchange data objects (structured data) between applications and for data storage.
Within iSHARE, JSON is used as data structuring standard for scheme related communication. For the most recent version of the JSON specification visit json.org.
JWT
JWT (JSON Web Token) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. Because of its size, it can be sent through an URL, POST parameter, or inside an HTTP header. Additionally, due to its size its transmission is fast.
A JWT is used in iSHARE when exchanging claims between parties. These claims are signed using the JSON Web Signature (JWS) standard to ensure non-repudiation of these claims. JWT section describes how iSHARE uses JWTs and what the specifications for iSHARE JWTs are, while the official standard can be found at tools.ietf.org (RFC 7519).
OAuth 2.0
OAuth is a widely used security standard that enables secure access to protected resources in a fashion that is friendly to web APIs. It is a delegation protocol that provides authorization across systems. OAuth is about how to get a token and how to use a token. OAuth replaces the password-sharing anti pattern with a delegation protocol that’s simultaneously more secure and more usable. OAuth focused on solving a small set of problems and solving them well, which makes it a suitable component within larger security systems.
iSHARE uses the OAuth 2.0 protocol for authenticating parties and providing access tokens when requesting access to a service within iSHARE. For the most recent version of the OAuth 2.0 specification visit oauth.net.
OpenID Connect 1.0
OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol specific for human subjects. It is used to obtain identity information for a human subject. Besides authenticating a human subject, the OpenID Connect flow can also be used to communicate information of the human subject to a server. For more information please read official OpenID Connect specification.
Just as in OAuth 2.0, iSHARE deviates from the original standard to allow for information exchange with previously unknown parties. Identity Providers need to provide API access to iSHARE participants based on whitelisted PKI, clients need not to be pre-registered at an Identity Provider.
PKI
The UNIX timestamp is a way to track time as a running total of seconds. This count starts at the UNIX Epoch on January 1st, 1970 at UTC. Therefore, the UNIX time stamp is merely the number of seconds between a particular date and the UNIX Epoch. For example, on 7:34 PM (UTC) on the 4th of September 2018, 1536089675 seconds have passed since January 1st, 1970 at UTC. The UNIX formatted timestamp is therefore 1536089675. This Unix formatting of UTC point in time technically does not change no matter where you are located on the globe. This is very useful to computer systems for tracking and sorting dated information in dynamic and distributed applications both online and client side.
In iSHARE all dates and times MUST be communicated in UTC time. All dates and times MUST be formatted in the Unix timestamp format.
XACML 3.0
XACML (eXtensible Access Control Markup Language) is an XML-based specification that is designed to control access to applications. One of the main advantages of this specification is that applications and systems with their own and different authorization structure can be integrated into one authorization scheme. authorization and the rules surrounding it can be managed centrally regardless of authorization mechanism of the applications themselves. This phenomenon is called externalisation. XACML is derived from SAML and provides the underlying specification for ABAC (Attribute-Based Access Control). XACML is also suitable to be used in combination with RBAC (Role-Based Access Control).
Moreover, with the help of XACML authorization can be arranged and managed in detail. This is called fine-grained authorization . XACML supports the use of security labels, rules with arbitrary attributes, rules with a certain duration and dynamic rules.
In XACML two main functions can be distinguished. One function defines the criteria with which authorization are assigned, such as ‘only an experienced user from department X is allowed to modify documents’. The other function compares the criteria with the rules or policies to determine whether a person is allowed to perform the operation on the object or not.
The architecture of XACML is fairly complex. This is partly due to the fact that it is difficult to fit the various components of XACML in the application landscape. These components should be positioned in such a way that the owner of the data can somehow control the authorization to his or her data, but at the same time the components should be positioned in such a way that the performance is not negatively influenced. This is extra important when independent parties need to cooperate with each other and want to jointly organise the access to their applications. Finally, applications need to be compatible with XACML.
XML-based standard for defining authorisation policies. Within iSHARE, a JSON port of XACML 3.0 is used to enable parties to communicate delegation evidence. Visit docs.oasis-open.org for the most recent version of this specification.
X.509
In cryptography, X.509 is a standard defining the format of public key certificates. X.509 certificates are used in many Internet protocols, including TLS/SSL, which is the basis for HTTPS, the secure protocol for browsing the web. They are also used in offline applications, like electronic signatures. An X.509 certificate contains a public key and an identity (a hostname, or an organization, or an individual), and is either signed by a certificate authority or self-signed. When a certificate is signed by a trusted certificate authority, or validated by other means, someone holding that certificate can rely on the public key it contains to establish secure communications with another party, or validate documents digitally signed by the corresponding private key. The most recent version of this specification can be found at tools.ietf.org (RFC 5280).
X.509 is used in iSHARE as a standard defining the format of public key certificates.
Last updated
