Pryv.io Functional Requirements Specifications

1. Introduction
Date 1st February 2024
Documents Version 1.3
API-Version 1.8.x - 1.9.x

This document describes the functional specifications for the Pryv.io middleware system: the capabilities and functions that the system must be capable of performing.

This document applies only to Pryv.io distributed under Enterprise and Open Pryv.io releases.

2. Terms and acryonyms

Access

A set of permissions relative to a user account resources. The access is identified by an Access Id and presented to the API as an Access token. See Accesses concept.

Access Token

A string of characters used for transacation that require Authorization. An acces token is linked to one Access Token, the content of a token must remain a secret and is set along with each request. Access Tokens are the primary identifier for the AUTHOR of an API call.

Data Subject

As part of personal data reglementations and policies such as GDPR or HIPAA, refers to any individual who can be identified directly or indirectly by a subset of data, either identifier or factors specific to a person’s identity. By extension, the person whose data is collected, held or processed.

On Pryv.io, each individual’s data is held on a per Data Subject User Account. Data Subject is also refered as User.

3. Functional Requirements

This section describes the functional requirements associated with a specific feature. Each functional requirement specifies functions that a system or component must be able to perform and that must be present for the user to be able to use the services provided by the feature.

3.1. Overall Description

Pryv.io is a middleware which aims to provide personal data management.

As a middleware, Pryv.io does not provide User Interfaces (UI), nor physical storage or infrastructure. The system is composed of several components being:

  1. One or multiple core components: responsible for the core functionalities such as data storage and access control.

  2. One or multiple register components: responsible for linking a data subject’s storage to the corresponding core component responsible for its data management.

3.2. Connectivity and interfaces

idREQ_CON_HTTP
Title
The system shall be accessible through an HTTP API
Desc

Access to the system is done using a Web API.

Refs
  1. The Pryv.io HTTP API is described online at https://pryv.github.io/

3.3. Data Types

idREQ_DATA_DEFTYPE
Title
The system shall provide default data types validation
Desc

Default data types are available in the system for which content is validated.

idREQ_DATA_CUSTTYPE
Title
The system shall accept custom data types
Desc

It is possible to define custom data types.

idREQ_DATA_CUSTVAL
Title
The system shall allow to define custom type validation
Desc

It is possible to define validation rules for custom-defined types.

3.4. Streams

See: Streams concept

idREQ_STREAM_BASE
Title
The system shall permit Streams management through the specified actions
Desc

The following actions are provided by the system to manage Streams:

  • Create
  • Read
  • Edit
  • Delete
  • Share

3.5. Events

See: Events concept

idREQ_EVENT_BASE
Title
The system shall permit Events management through the specified actions
Desc

The following actions are provided by the system to manage Events:

  • Create
  • Read
  • Edit
  • Delete
  • Share
idREQ_EVENT_ATTACHMENTS
Title
The system shall permit to Add, Update and Delete files on Events
Desc

3.6. Data life cycle management

Each part of the life cycle is further described.

idREQ_DLC_BASE
Title
The system shall manage all data life cycle parts as described here
Desc

The following actions are provided by the system to manage the data life cycle:

  1. Collect and aggregate
  2. Store
  3. Use and aggregate
  4. Share
  5. Disposal

3.6.1. Collect

idREQ_DLC_COLLECT
Title
The system shall allow data input through multiple sources
Desc

The system ensures that data can be collected from multiple sources through its HTTP API.

Data Sources can be:

  • Web services
  • IoT and other mobile devices
  • Electronic records

3.6.2. Store

idREQ_DLC_STORE
Title
The system shall ensure data storage
Desc

The system stores collected data records and associated information on physical storage.

idREQ_DLC_INTEGRITY
Title
The system shall add data integrity hash on attachments, events and accesses.
Desc

If the corresponding setting is activated, the system will compute a content hash integrity hash on attachments, events and accesses. This hash shall be used:

  • to check the integrity of data when Adding it to the system
  • to check the integrity of data when Reading it from the system

3.6.3. Use and aggregate

idREQ_DLC_USE
Title
The system shall provide data retrieval and aggregation from different sources
Desc

The system provides retrieval of data independently from the source with a
Selection by:

  • Time
  • Stream
  • Tag
  • Type
  • Deletion state
  • Modification date
idREQ_DLC_AGG
Title
The system shall provide methods to aggregate data from multiple subjects
Desc

The model of Streams and Events is designed to easily merge data from multiple subjects.

3.6.4. Share

idREQ_DLC_SHARE
Title
The system shall provide data sharing with external actors
Desc

The system provides a sharing mechanism that allows external actors to access data.

idREQ_DLC_EXPORT
Title
The system shall provide the possibility to export all the subject’s data out of the system (extra-system migration)
Desc

The system provides export capability and tools to export all data of a subject. The exported format facilitates interoperability.

3.6.5. Disposal

idREQ_DLC_DEL
Title
The system shall ensure deletion of data
Desc

The system provides the following information to check the existence of an item:

  • Deleted state
  • Complete deletion
  • Track of deleted items for synchronization

3.7. Access Control

idREQ_ACC_SELECT
Title
The system shall provide granular access per data subject
Desc

The system provides the following parameters to define the permissions of Accesses:

  • Streams list
  • Tag list
  • Expiration date

Read and Write levels are provided at Stream and Tag levels

idREQ_ACC_CONTRACT
Title
The system shall provide storage of contractual terms relative to an Access
Desc

The system provides extra properties for each Access to store contractual terms. These terms should be relative to the permissions of an Access.

If terms are displayed to a user during an Access request flow and accepted, the contractual terms are stored as a proof of Consent.

idREQ_ACC_ENFORCE
Title
The system shall enforce access control
Desc

The system:

  • denies invalid or expired Accesses
  • authorizes valid Accesses based on their permissions property
idREQ_ACC_BASE
Title
The system shall permit accesses management through the specified actions
Desc

The following actions are provided by the system to manage Accesses:

  • Create
  • List
  • Update
  • Delete
idREQ_ACC_REQUEST
Title
The system shall allow the external services (Apps) to request access to data by means of access control
Desc

Access request and enforcement flow involves the following actors with specific actions:

  • App: Request, Obtain
  • Data Subject: Accept, Deny
  • System: Authenticate, Enforce
idREQ_ACC_TYPE
Title
The system shall provide Personal, App and Shared type of Accesses
Desc

The system provides Personal, Apps and Shared Accesses.

Refs
  1. Accesses concept description
idREQ_ACC_DELEGATE
Title
The system shall provide delegation of access control
Desc
  • Personal
    • can manage App and Shared Accesses
  • App
    • can create Shared Accesses within their scope
    • can manage Shared Accesses it created
idREQ_ACC_REGISTER
Title
The system shall provide management for received Accesses at a user level
Desc

The system provides Followed Slices to manage received Accesses with the following actions:

  • Create
  • Update
  • Delete
  • List
Refs
  1. Followed Slices API documentation

3.8. Notifications

idREQ_NOTIF_EVENT
Title
The system shall provide notification capabilities for changes at Event level
Desc

The system provides an Event change notification when the following occurs at Event level:

  • Creation
  • Modification
  • Deletion
idREQ_NOTIF_STREAM
Title
The system shall provide notification capabilities for changes at Stream level
Desc

The system provides a Structure change notification when the following occurs at Stream level:

  • Creation
  • Modification
  • Deletion
idREQ_NOTIF_LISTEN
Title
The system shall provide listener registration capabilities
Desc

The system provides Websockets and Webhooks based implementations to register a listener.

3.9. User management

idREQ_USER_BASE
Title
The system shall permit user management through the specified actions
Desc

The following actions are provided by the system to manage Users:

  • Creation
  • Deletion
idREQ_USER_LOGIN
Title
The system shall provide authentication of a user upon login
Desc

The system provides authentication on login with a userId/password pair.

idREQ_USER_LOGOUT
Title
The system shall provide logout
Desc

The system provides invalidation of authorization.

idREQ_USER_EMAIL
Title
The system shall provide email property management
Desc

The system provides email property management at a User level:

  • at the creation of a user
  • using an API call to change the email property of a user
idREQ_USER_EMAILID
Title
The system shall provide retrieval of userId provided a email address
Desc

The system provides discovery of userId by email.

idREQ_USER_LIST
Title
The system shall provide a list of Users (Data Subjects)
Desc

The system provides a list of users registered on the platform with the following properties:

  • registration date
  • invitation token used for registration

3.9.1. Invitations

idREQ_USER_INV_MANY
Title
The system shall provide multiple usage invitation tokens
Desc

The system can be provided a list of invitation tokens that can be used multiple times.

3.9.2. Profile

idREQ_USER_PROFILE_PRIVATE
Title
The system shall provide a storage of properties at a private user level
Desc

The system provides storage of key/value pairs at user account level only available for Personal Accesses.

idREQ_USER_PROFILE_PUBLIC
Title
The system shall provide a storage of properties at a public user level
Desc

The system provides storage of key/value pairs at user account level available publicly.

idREQ_USER_PROFILE_APP
Title
The system shall provide a storage of properties at an App access user level
Desc

The system provides storage of key/value pairs at app level only available by App Access.

3.10. System requirements

3.10.1. Hardware

idREQ_SYSTEM_HWRE_OS
Title
The system shall run on a UNIX operating system
Desc

The following UNIX operating systems are supported:

  • Ubuntu Server 18.04 LTS to Ubuntu Server 22.04 LTS. On Unbuntu 20.04 and 22.04 the local dns must be deactivated (systemd-resolved)
idREQ_SYSTEM_HWRE_CONTAINER
Title
The system should be packaged in a container for delivery and deployment
Desc

The system is delivered packaged in Docker containers

Refs
  1. Docker.com web site

3.11. Non-Functional Requirements

3.11.1. Security

idREQ_SEC_NOAUTH
Title
The system shall store in log files unauthorized API calls
Desc

Unauthorized API calls are logged on the host operating system using syslog.

idREQ_SEC_PASS
Title
The system shall support password policy rules
Desc

Rules for password complexity (length, character categories), age (minimum, maximum i.e. expiration) and reuse (i.e. history) can be enabled in the platform settings.

idREQ_SEC_AUTH
Title
The system shall store in a log file authorized API calls
Desc

Authorized API calls are logged on the host operating system using syslog with mechanisms to identify the Access token that was used.

idREQ_SEC_COM
Title
The system shall provide encryption for all inboud communications
Desc

The system is provided with a component ensuring SSL termination. This component can be replaced by the customer.

idREQ_SEC_ENC
Title
The system shall provide mechanisms for client-side encryption
Desc

The data model supports client-side encryption by encapsulating encrypted data into the encrypted/* data type.

Refs
  1. Encrypted data-type reference

3.11.2. Auditability

idREQ_AUDIT_AUTHOR
Title
The system shall provide auditability of data edition
Desc

Events, Streams and Accesses expose the date of modification and used Access token.

The goal is to be able to answer the what and when questions, provided a specific who.

idREQ_AUDIT_CALLS
Title
The system shall provide auditability of all API calls per Access token
Desc

All HTTP calls POST, PUT, GET, DELETE are logged on the host operating system using syslog with mechanisms to identify the used Access token.

The goal is to be able to answer the what and when questions, provided a specific who.

3.11.3. Recoverability

idREQ_BCKP_BASE
Title
The system shall be fully recoverable using the latest backup available
Desc

The system’s data shall be recoverable from backup files.