Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Developed by Ain Aaviksoo (Estonian Telecommunications Union), Benjamin Balder Bach (fmly Danish Tax & Revenue), Lal Chandran (MyData Global, iGrant.io), Philippe Page (MyData Global, Human Colossus Foundation). And advisors Dr. P. S. Ramkumar (ITU), Max Carlson (GovStack), Sasikumar Ganesan (MOSIP)
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document. Any implementation MUST adhere to all requirements from GovStack Security Requirements.
Personal data MUST be kept private and never shared with any parties, except where specific authorisation has been granted. The Consent Building Block shall follow the privacy principles as laid out in the GovStack architecture.
Logs MUST be kept in a database of all created, updated, or deleted records. Logs MUST include timestamps and identify the user and affiliation that performed the transaction.
In general, the Consent Building Block shall follow the authentication and authorisation requirements as laid out in the . For clarity, Consent Building Block's API endpoints are invoked with a client-supplied API key which must defer to the Identification and Verification Building Block in order to verify the role and/or scope of the API key matches the API endpoint to which it is supplied. This is mentioned here, as this definition is drafted without clear guidance in the OpenAPI specification for the handling of roles and scopes.
In general, the Consent Building Block shall follow the authentication and authorisation requirements as laid out in the Govstack architecture. For clarity, Consent Building Block's API endpoints are invoked with a client-supplied API key which MUST defer to the Identification and Verification Building Block in order to verify the role and/or scope of the API key matches the API endpoint to which it is supplied. This is mentioned here, as this Definition is drafted without clear guidance in the OpenAPI spec for the handling of roles and scopes.
All dates should follow ISO 8601.
RFC 7159 - The JavaScript Object Notation (JSON).
OpenAPI Version 3.1.0.
RESTful APIs follow TM Forum Specification: “REST API Design Guidelines Part 1” (requirement derived from GovStack Architecture and Nonfunctional Requirements).
The version history table describes the major changes to the specifications between published versions.
For a full changelog, please see .
| Version | Authors | Comment |
|---|
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Consent Building Block enables organisations to enforce Data Policies that require signed consent by Individuals for the use of their Personal Data. Its key purpose is to allow individuals to view Consent Agreements and sign or withdraw their consent on what Personal Data is used and accessible to organisations. It also clarifies the Data Policy applied, such as the purpose, retention period, jurisdiction, third-party data sharing, etc.
The Consent Building Block implements the key functionalities described in the . It includes the ability to configure consent agreements by an organisation admin, present consent requests towards individuals, capture consents, enable queries if consent exists, or not, and enable independent audit of consents.
The functionalities are derived from the consent agreement lifecycle and categorised according to the described above. While the consenting workflows (as described above) are implicitly considered the centrepiece of the Consent Building Block, it is important to realise that the integrity of consent management can only be achieved if robust configuration before and auditing after the Consent Agreement signing and Consent Record verification activities are in place. Hence, the functionalities are described following the logical sequence of the consent agreement lifecycle and they are all equally important components of the Consent Building Block.
The Consent process (creating and signing Consent Agreements and Consent Records) is initially managed in the application provided by the Organisation that is legally required to collect the consent. Since it can be either a Data Consuming organisation or a Data Providing organisation, the Consent Building Block allows both to be able to verify their conformance with the underlying Data Policy, both organisations must be able to access and use the application.
While the Actors generally fall in line with the categories of the functionalities, it is important to realise that “auditing” functions in the narrow sense, verifying if data processing is being (or has been) processed according to the Data Policy requiring a consent, is relevant to various entities involved in the data processing. For this reason, the generic “verification” activity may be executed as part of various workflows satisfying the needs of different actors.
Following is the first core set of key functionalities of the Consent Building Block. For potential future developments of the specification follow the work in progress at .
The Administrator (Data Provider or Data Consumer Admin) configures the Consent Building Block on behalf of the organisation. For simplicity, it is foreseen that one organisation involved in the data processing transaction (that is either Data Provider or Data Consumer) takes the responsibility for the configuration of the Data Policy and respective Consent Agreements(s), and so that the organisation’s Administrator maintains the required configurations.
The main Administrator actions expected to perform via Consent Building Block are:
configuring Data Policies, requesting and signing Consent Agreements with Individuals;
viewing (reading, exporting) the Consent Agreements and relevant reports;
event-driven (opt-in or opt-out) subscription to (notifications of) changes in Consent Agreements;
logging and maintaining an auditable overview of all Personal Data transactions according to Consent Agreements as well as configuration versions.
The table below summarises the key use cases identified for an organisation's Administrator. Organisations can be Data Consumers or Data Providers, i.e. the organisations legally delegated the responsibility for collecting consent for the systems handling Personal Data processing.
The capabilities for individuals that Consent Building Block supports are:
viewing and understanding Data Policies applying to their Personal Data processing;
agreeing and disagreeing with and toggling between the conditions of Personal Data use as described in the Consent Agreement;
obtaining copies of their Consent Agreement(s);
delegating their consent rights (out-of-scope for current technical release).
The scope for the current version of Consent Building Block assumes that the Individual is acting for themselves. Ultimately the Consent Building Block will include in the Consenting Process the capacity to sign a Consent Agreement in the name of another individual - to act as the Delegate, which is used as the criterion for technical implementation. However, the Delegate and the Individual relationship is expected to be maintained outside of the Consent Manager, which assumes that the person signing the Consent Agreement (i.e. Consenter) has been authorised to do so.
The table below summarises the key use cases identified for the Individuals.
Important note: In the Consent Building Block, we define the Data Processing Auditor's role (see 1.3 Terminology and 1.5.3 Actor definition) as an organisation's auditor implementing the Consent Building Block. The auditor role will most probably be akin to a Data Protection Officer (DPO), possibly from an external third-party organisation and involve activities outside of the Consent Building Block.
To avoid ambiguity, we use the precise term Data Processing Auditor to stress the specificity of tasks to be performed by and for the Consent Building Block; all other actions not within the Consent Building Block's scope are considered as an external prerequisite and as a “black box” activity. With respect to audit, this role is distinguished from the data policy auditor. The Data Processing Auditor relies on an audit universe defined by the control and risk management of the specific project and context (i.e. outside the Consent Building Block). “Who needs to consent to what” is the outcome of a DPIA (Data Protection Impact Analysis), ensuring that the data policies are compliant with the relevant data protection regulations for the project.
The main actions a Data Processing Auditor (or Data Protection Officer, DPO) is expected to perform via Consent Building Block are:
auditing tracking the consents (opt-in/opt-out);
auditing tracking Data Policy changes and configuration conformance with it;
viewing (reading, exporting) the Consent Agreements and relevant reports in a verifiable form.
For the implementation of a specific use case, it is important to distinguish the Data Processing Auditor, an actor described here, from a data policy auditor, an actor of the risk organisation. It is expected that the two roles are coordinated in the risk management process. Within the Consent Building Block, the Data Processing Auditor performs the tasks that will allow a data policy auditor to confirm that the implemented system complies with existing regulations demanding consent.The table below summarises the key use cases identified for the Data Processing Auditor.
Also to consider: “READ CONSENT STATUS” use-case is also used by any workflow (and Actor) that requires verification of the consent status (for example, before executing the data transfer from Data Providing System to the Data Consuming System).
As described above under , there may be an unlimited number of business processes that require consent. The following scenarios are but a few examples illuminating how appropriate access to data can and should be handled when processing or consuming data with the support of Consent Building Block functionalities.
Scenario | Source Building Block | Target Building Blocks | Description |
1.1 Querying: Which Consent Agreement is needed for specified data processing/ consumption? | Any | Workflow Building Block | Consent Building Block does have knowledge or state to resolve which Data Consumer or Data Producer requires consent. Everything regarding consent has a precondition that a decision is made and manifested in the Workflow Building Block or any other Data Consumer. |
1.2 Data processing/ consuming system stores/fetches data with consent + prompts the user if none exists | Any | Consent Building Block | Given an Agreement ID and a User ID, the Consent Building Block can resolve if consent exists and possibly prompt the user. Workflow Building Block is especially inappropriate here because of User Interface integration and a blocking and sequential call stack. |
1.3 Data processing/ consuming system stores/ fetches data with consent, no halts operations without consent | Any | Workflow | Given an Agreement ID and a User ID, the Workflow Building Block can complete an atomic action requiring consent. Operations shall not proceed if consent does not exist. |
1.4 Data processing/ consuming system stores/ fetches data with consent, consent is prompted asynchronously | Any | Workflow | The Workflow Building Block may halt operations and asynchronously prompt the user for consent if none exists (or is invalid). After fetching consent, the Workflow Building Block should revert to the targeted data consuming/ processing operation. |
1.5 Appropriate access to data that does not require consent | Any | Workflow | Not necessarily related to Consent Building Block. |
1.2-1.4 Side effects | Workflow | Any attempt to read consent and process/consume data is logged and auditable. |
2.1 Inappropriate access: Data processing/consuming system inappropriately stores/fetches data without consent | Any | N/a | Any consent-requiring data access is assumed logged. Auditing of inappropriate data access is only possible when a log trace exists. |
3.1 | Workflow | Consent | Given an Individual, query if active Consent Records exist (for instance, to spot if other external data needs to be kept). |
4.1 | Any | Consent | Fundamental individual rights (General Data Protection Regulation/ Data Protection Act/ Right to be Forgotten/etc.) |
4.2 | Any | Consent | Fundamental individual rights (General Data Protection Regulation/Data Protection Act/etc.) |
0.8.0 | Ain Aaviksoo, Lal Chandran, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | Release submitted for internal GovStack review |
0.9.0RC1 | Ain Aaviksoo, Lal Chandran, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | Release submitted for Technical Advisory Committee Review |
0.9.0RC2 | Ain Aaviksoo, Lal Chandran, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | Updated according to the Technical Advisory Committee review feedback |
1.0.0 | Ain Aaviksoo, Lal Chandran, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | First public release. |
1.1.0 (in development) | Ain Aaviksoo, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | (see changelog) |
2.0.0 (planned) | Ain Aaviksoo, Benjamin Balder Bach, Philippe Page, Dr. P. S. Ramkumar | (see changelog) |
Consent use-cases | Link(s) to the UCS |
CREATE CONSENT AGREEMENT - Here, an organisation Administrator creates a Consent Agreement based on the Data Policy requirements. |
UPDATE CONSENT AGREEMENT - Here, an organisation Administrator updates the Consent Agreement based on the Data Policy requirements. |
READ CONSENT AGREEMENT - Here, an organisation Administrator reads the Consent Agreement. |
DELETE CONSENT AGREEMENT - a special case of consent agreement update. |
CONSENT AGREEMENT CHANGE NOTIFICATION - Notifications for Data Providing and Data Consuming Systems, as well as Individuals upon changes to Agreement or Policy configuration. |
Consent use-cases | Link to the UCS |
VIEW CONSENT - Here, the Individual views the Consent Agreement and the conditions for Personal Data processing (with adequate clarity for informed understanding). This includes obtaining copies of the consent agreement. |
GIVE CONSENT - Here, the Individual signs a Consent Agreement during a data sharing workflow. Note that this can also happen offline without data sharing in place. |
WITHDRAW CONSENT - Or update existing consent |
Consent agreement change notification |
Consent use-cases | Link to the UCS |
AUDIT CONSENT - Query the Consents related to individuals or policies (opt-in/opt-opt) |
MONITOR POLICY UPDATE- Tracking Data Policy changes and configuration conformance with it; |
READ CONSENT STATUS - Viewing (reading, exporting) the Consent Agreements and relevant reports in a verifiable form |
VERIFY CONSENT INTEGRITY - Ability to check the integrity of the signed agreements |
This section provides a reference for APIs that should be implemented by this Building Block.
This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Consent Building Block can be found in this GitHub repository.
The following is an automated rendition of our latest OpenAPI YAML specification.
None
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
This section lists workflows that this Building Block must support. Other workflows may be implemented in addition to those listed.
The Workflow Building Block triggers the need for consent as part of the general business flow. The assumption is that a consenting process never exists outside of a purposeful comprehensive business process. Hence, it is important to define and control the data processing activities as part of a holistic data service.
This section lays out key universal consent workflows that can be re-used within the various use cases (see Workflow Building Block). This enforces the best practices for organisations to adhere to Personal Data processing standards in any given context and jurisdiction. In these sequences, we have removed the Digital Registries Building Block in the sequence for simplicity. It will store all persistent consent data.
The first and somewhat unique use case is related to the need for consent when the Individual is not yet provisioned in the System processing the data. In such cases, the workflow requires the creation of a valid and trusted Foundational ID to be linked with the Consent Record. Below is shown how a pre-registration use of Consent's Workflow works.
At the very beginning, the registration process will know which Agreement IDs are eligible for registration and fetch the Agreement(s) and their related objects, such as AgreementPurpose, AgreementData, Controller and Policy.
The signing process is initiated by calling the API endpoint /service/individual/record/consentrecord/draft/ which produces two resulting instances: ConsentRecord, Signature. None of these are stored in the database, so they have no id value supplied. They will be used after the registration process is completed.
Once the registration is completed, and a functional or foundational ID (which ever is desired to use, the Consent BB uses the notion of "external ID" here) is known by the Identity BB, the registration process should resolve if this ID has previously been used to store consent by a request to /service/individuals/. If an Individual object does not exist, a call is issued to /service/individual/ to create the individual in the Consent BB with a reference used by the Identity Building Block.
At the end of the registration, the API endpoint /service/individual/record/consentrecord/ is called with the draft ConsentRecord and Signature objects to be saved.
ConsentRecordWhen a draft is created, the Consent BB should issue a pair of object instances that are not saved in the database. They have the same schema as the real database objects, but the id field is left blank.
The Signature object would normally contain the content of a Revision object in its payload field. In this case, it will contain the content of a Revision object that was not stored in the database when it was generated, so it doesn't have an ID yet.
We use the two boolean flags Revision.signed_without_object_id and Signature.signed_without_object_reference to denote that the Revision and Signature objects were hashed and signed without any reference to a database row. However, these fields are filled in later! When Signature and Revision objects are validated by serializing and hashing the data that they claim to represent, we need to note these two flags so we don't generate the wrong hashes or compare serialized values wrongly.
Agreement and Policy objects are revisioned and if the registration process wishes to initiate a different revision from the latest active revision, it should be equipped with the knowledge of the revision IDs.
In cases where a valid ConsentRecord and Signature pair already exists in the system, those should be returned instead, and the client-side can understand from the timestamp of the object that it has been created at a previous occasion. This can be resolved by calling /service/individual/record/agreement/{agreementId}/.
If the latest active Agreement or Policy revisions change, then those changes have to be detected when fetching related objects. The expected Revision ID is added to calls that fetch related objects and APIs should fail if there is a mismatch and a different set of related objects are returned compared to the latest active Agreement.
CONSENT CAN BE OMITTED BY THE USER. The Consent BB does not know about this unless informed, since the Application is responsible for the UI. If there is a need to record an opt-out, this is possible to do with the same process, but simply marking the ConsentRecord as an explicit opt-out. The Registration process may also skip recording the opt-out and proceed to an alternative path.
In more frequent situations, when the individual is already provisioned in the System (post-registration), the consent workflow uses the existing ID tokens, and only the ConsentRecord is to be created.
As with the Registration Workflow, the Application needs to know IDs of Agreement objects that are eligible for the consent beforehand. It may optionally use a Revision ID for an Agreement to specify a specific version of the Agreement. Essentially, the application developer should embed these IDs in the process as predefined data.
In this workflow, the Application has authenticated the individual (user), and if the user consents to the presented Agreement, the ConsentRecord will be stored with a relation to an Individual entity in the Consent BB. The Individual schema has a number of optional fields that will relate it to the original user's identity in a desired manner. In other words, the identity of the user is exposed to the Consent BB in a desired manner. There are several options:
The individual can be managed through a Foundational ID, Functional ID which can be useful for the Consent BB to allow the user to manage all their ConsentRecords at a later stage.
A session-related ID that the application or other data consumers can otherwise use at a later stage.
An obscurified ID that can be resolved through the Identity BB such that all ConsentRecord management can only be performed with a relation to the real individual through authorization of the Identity BB.
No matter which Individual ID is used, the Application is responsible for either fetching an existing or creating a new Individual object in the Consent BB.
The Application is responsible for presenting the UI and calls the necessary endpoints of the Consent BB to store the ConsentRecord.
A draft ConsentRecord and Signature object is handed to the Application, which it should finalize and submit back.
There are several options for finalizing the draft Signature object: The individual may be requested to explicitly sign the consent through Identity BB and eSignature BB. However, another trusted signing party may also be eligible to record and sign the validity of the ConsentRecord object.
The Application may want to check if consent has already been obtained! This can be done at several stages, if there is a need to guard against parallel processes.
A ConsentRecord may be created at first, but if the signing process fails and no Signature object is created, the Application should perform due diligence and delete the ConsentRecord.
Consent can always be omitted during the process or at any later stage. The Application needs to provide an alternative path. This can for instance be handled with the Workflow BB.
In this universal workflow, we check if a valid ConsentRecord exists or not for a given data processing event within a business process. This may be the immediate continuation of a consenting workflow by the same System that acquired the ConsentRecord or it may be used by a separate business process by a different Application or at a different moment in time. The same verification workflow may be also used for auditing purposes.
In order to query for the existence of a ConsentRecord, the Application needs to know about an Individual and an Agreement.
The Individual can be resolved through a query using the RegistryReference schema as a parameter. The Consent BB will then return matching Individual objects.
As is seen in other workflows, the Agreement is resolved by preexisting knowledge of the Agreement ID, and the Application may further use a specific Revision ID of the Agreement or ask for the latest active Agreement by not specifying a Revision.
By using the Individual and Agreement IDs, it is possible for the Application to fetch the latest active ConsentRecord and Signature to resolve the state of consent.
TODO
This section provides context for this Building Block.
The Consent Building Block enables services for individuals to approve the use of their Personal Data by defining the principles, functions, and architecture of an information system. For organisations that process Personal Data, it provides the ability to know the individual's will and legitimately process such Personal Data. The Consent Building Block is a process-oriented GovStack Building Block facilitating auditable bilateral agreements within a multi-agent environment that integrates with most other Building Blocks.
This specification has used several available and recognised open standards below and legal frameworks (such as the GDPR) for laying the groundwork for its approach to consent.
Kantara Initiative: Consent Specification
ISO 29184: 2020: Online Privacy Notices and Consent
ISO/IEC 29100:2011: Privacy Framework
ISO/TS 17975:2022: Health informatics — Principles and data requirements for consent in the Collection, Use or Disclosure of personal health information
ISO/IEC TS 27560:2023: Privacy technologies — Consent record information structure
In the GovStack context, consent is understood as a voluntary declaration by an individual to approve the processing of their Personal Data. It is one specific justification for Personal Data processing that is assumed to be required by legal or ethical conditions. It assumes that the person can decide on processing their Personal Data, managed in and by other GovStack Building Blocks, and also that the person is free to withdraw their consent at any time.
Some examples of such consent are:
allowing a healthcare provider to fetch socio-demographic data from a government-run population registry to provide adequate primary healthcare services.
allowing a government official to fetch relevant data from other/multiple government-run registries to analyse the eligibility for a social benefit programme.
allow a government official to send Personal Data to a bank for cash transfers on behalf of the government.
The use of consent should be avoided in cases as below, which are not part of this specification:
When a person is simply informed of the processing of the data by the organisation as part of the service provided under contract or by an authority.
When consent does not have to be obtained in a situation where the entity does not identify or cannot identify people with reasonable effort.
Lays out the pre-conditions needed for anyone to use the Consent Building Block.
Data Disclosure Agreements between organisations are already in place. For example, a healthcare organisation has already got the required authorisation to use the citizen data registry.
To link a Consent Agreement with the specific Individual, Consent Building Block assumes the authentication and authorization to be handled in a trusted manner outside of it (see below).
Within the early scope of the Consent Building Block, the act of delegating is kept outside the scope of the Consent Building Block. It is assumed that the authorisation to act on behalf of someone else is already resolved.
It is the organization's (a Data Provider or a Data Consumer) obligation to manage and implement internal policies toward its employees relating to their responsibilities for Personal Data processing integrity, specifying it in the employment contract or by other means.
The life cycle of a consent agreement starts and ends within the organisation responsible for the information system. The organisation knows the context in which the information system operates and the intended purpose of the service. The rules and regulations to be applied for a given level of assurance define the functional framework for consent management.
Consent Building Block deals with transparency on data usage in a given context. Thus privacy-by-design of the system's actors is often an excellent guiding principle for interpreting international, national, and organisational policies and governance principles to implement the functional consent framework. A tangible outcome from a Data Protection Impact Analysis (DPIA) is a structured approach that can deliver the input for the actual implementation of the Consent Building Block.
Individual consent is captured within the context of digital interaction. This interaction is composite of all the information systems involved, not solely the Consent Building Block. Thus, the legal and ethical boundaries of consent are defined in the entirety of the interaction. In particular, consent, as defined by ISO/TS 17975:2015(E), should be seen as a "set of agreements and constraints" that an informed and knowledgeable [individual] agrees to apply to their data processing. This definition, not based on the purpose of the data usage, can lead to a consent management framework also incorporating authorisations or unrelated constraints of the system. For example, in health information and healthcare service delivery, consent is also the process whereby a set of constraints is agreed upon so that information may be collected and used or disclosed. However, it is also the outcome of the process. As a rule of thumb, limiting unintended secondary usage of data is helpful to separate "consent" for a purpose from "consent" as an agreement to constraints and authorisation imposed by the system's functional requirements.
As a result, the organisation responsible for the information system is the driver of the definition of the functional consent management framework. It is also the function of the organisation to design the workflow for obtaining and processing the consent in a way that is purposeful, but not annoying for individuals or data processors with unnecessary bureaucratic overhead. From this framework, the Consent Building Block achieves its purpose by employing Consent Agreements that contain the following:
A data policy that could be reused across multiple consent agreements (for example, based on the General Data Protection Regulation or any specific regulation)
The purpose of consent, processed data attributes
Signatures
A consent agreement life-cycle has four main phases, as illustrated in the figure below:
Definition: In this phase, the organisation (a Data Provider or a Data Consumer) adopts and defines a Data Policy that applies to the industry or sector-specific data usage as a template. While this phase is considered a “black box” to the Consent Building Block, it is an essential reference point for configuration and compatibility checks in all following phases.
Preparation: In this phase, the organisation (Data Provider or Data Consumer) that intends to process Personal Data configures the Consent Agreement and relevant rules for its use. An organisation could use Personal Data for third-party data sharing, as an example.
Capture: In this phase, the Individual can review the Consent Agreement and, once agreed upon, it is captured in a Consent Record by the organisation and stored for verification. This allows an auditor to check and ensure records are in place to process the individual's Personal Data. In the future, this phase could also encompass delegation and other individual use cases.
Proof: In this phase, an organisation (A Data Provider or a Data Consumer) can demonstrate that a valid record exists for performing data processing within itself or with other organisations. This allows for internal usage and for an auditor to verify and ensure records are in place to process the individual's Personal Data.
Consent Building Block enables interaction between three (3) distinct user categories, which in combination create the necessary trust framework for the integrity of Personal Data processing. The actors are defined via distinct human roles to be performed in various consent life-cycle phases:
Individual as the subject of Personal Data processing;
Administrator of the information system exchanging the Personal Data;
Data Processing Auditor maintaining independent oversight of the data processing.
Below is the graphical depiction of the actors and their interactions; a more detailed description of the Consent Building Block capabilities is provided in Chapter 4 - Key Digital Functionalities.
It is important to realize that while the actors are defined via human roles, the consent-related interactions between such roles can be executed in machine-to-machine workflows performing tasks in the interest of the respective actor.
The overall relationship diagram is shown below.
The table below summarises the key relationships consumed during a consent transaction.
This section lists the technical capabilities of this Building Block.
The functional requirements section lists the technical capabilities that this Building Block should have. These requirements should be sufficient to deliver all functionality that is listed in the Key Digital Functionalities section. These functional requirements do not define specific APIs, they provide a list of information about functionality that must be implemented within the Building Block. These requirements should be defined by subject-matter experts and don’t have to be highly technical in this section.
Agreement Configuration Requirements.
It shall be possible to create a consent agreement, either based on an existing or new data policy template. Each consent agreement shall be under version control (REQUIRED)
It shall be possible to view an existing consent agreement (REQUIRED)
It shall be possible to update an existing consent agreement (REQUIRED)
It shall be possible to terminate an existing consent agreement (REQUIRED)
It shall be possible to capture and sign all changes to Consent Agreements, Consent Policies and Consent Records in tamper-proof Revisions (REQUIRED)
It shall be possible to subscribe to enable or disable a change notification towards users (REQUIRED)
It shall be possible to trigger a change notification when there are changes done to an existing consent agreement (RECOMMENDED)
The Building Block shall log all administrative functions (REQUIRED)
It shall be possible to view the associated consent agreement if it exists (REQUIRED)
It shall be possible to agree or opt-in or sign a consent agreement (REQUIRED)
It shall be possible to opt-out of a previously signed or agreed consent agreement (REQUIRED)
All individual consent actions shall be logged (REQUIRED)
It shall be possible to enable or disable consent change notification (REQUIRED)
It shall be possible to trigger a consent agreement change notification towards individuals (RECOMMENDED)
All consent logs shall be tamperproof, Audit logging (REQUIRED)
It shall be possible to view and verify a shared consent agreement (REQUIRED)
It shall be possible to view and verify a shared consent agreement (REQUIRED)
It shall be possible to filter and sort all objects’ revision histories can be filtered and sorted (REQUIRED)
Within the scope of Consent Building Block version 1.0, the required components are as given.
Consent Agreement Configuration Handler: handles the creation, updation & deletion of consent agreements for organisations. Organisations can be Data Providers or Data Consumers.
Consent Record Handler: enables Individuals to view data usage and consent record.
Notification Handler: handles all notification configurations and notifications requested by different subscribers.
Administrative User Interface and Client Software Development Kit: these are readily available components that can configure and use the services offered, making integration easy and low code.
Terminology used within this specification.
Following are the use-case descriptions required for individual consent service operations: viewing, giving, withdrawing and verification of consent as well as getting notifications about changes.
UC-C-PIC-I-001: View Agreements
UC-C-PIC-I-002: Give consent to fetching data
#option-a-self-registration-to-healthcare-application
#option-b-assisted-registration-to-healthcare-application
#option-c-individual-holding-the-data-for-registering-to-healthcare-application
UC-C-PIC-I-003: Withdraw or update existing consent
UC-C-PIC-I-004: Consent agreement change notification
Context: Postpartum and infant care
| ID | UC-C-PIC-I-001 |
|---|---|
There are three alternatives possible for giving consent:
Note: Here, the sequence shows the case for assisted registration flow. The same applies also for self-registration.
Diagram Source
This section provides information on the core data structures/data models that are used by this Building Block.
The resource model shows the relationship between data objects that are used by this Building Block. Data objects are ultimately modelled as OpenAPI schemas, however as the relational model isn’t easy to understand from OpenAPI specification, we start by presenting two high-level Resource Models.
When an individual gives consent, it is implied that the Organisation from one side and the Individual from the other side digitally sign a Consent Agreement and a respective Consent Record is created. The alternative scenario may be that signing takes place offline on a paper, but in this case, for the Consent Building Block to function properly, it is the responsibility of the Organisation to digitise (e.g. scan) the signed document and create digitally signed artefact to represent the Consent Record.
This Consent Record is a digital instance referencing the Agreement which is consented to or subsequently has consent withdrawn from.
This model expands the relationships between resources.
Revisions are maintained for Consent Records + Agreements and Data Policies, together with cryptographic signatures. This means that all changes are captured for auditability.
For a configured Agreement, data elements requiring consent are individually specified as Agreement Data. Agreement Data is not directly relatable to processes and internals of an external system. This architectural choice gives the consent model flexibility and greatly simplifies the architecture and consent lifecycle, but it does not contradict any additional features, allowing for relations to external systems.
Individual changes Consent Record.
Individual withdraws/revokes Consent Agreement.
Consent Record expires.
Consent Record expiry date changes.
Organisation replaces Consent Agreement.
Organisation replaces Data Policy.
Individual gives access to citizen data, using a third-party user interface (Consumer’s user interface). Example: COVID passports.
This specification is seen as a minimum requirement, all further implementations may add more structure but should not compromise the minimal integrity laid out. All property types are generic, and a concrete implementation may add further specificity to these models.
The OpenAPI definition file is maintained in YAML format, and OpenAPI schemas may be interactively explored in the next section.
As part of this specification, a set of fully structured example data are provided as a fixtures.json file. These fixtures are maintained and released together with the specification's mock application.
The mock application is an operational Docker Compose environment that satisfies all verification tests.
Following are four use-case descriptions required for Data Processing Auditor functionalities
| ID | UC-C-PIC-AT-001 |
|---|
| Building Block | Relationship description |
|---|---|
| ID | UC-C-PIC-I-002A |
|---|---|
| ID | UC-C-PIC-I-002B |
|---|---|
| ID | UC-C-PIC-I-002C |
|---|---|
| ID | UC-C-PIC-I-003 |
|---|---|
| ID | UC-C-PIC-I-004 |
|---|---|
| ID | UC-C-PIC-AT-002 |
|---|
| ID | UC-C-PIC-AT-003 |
|---|
| ID | UC-C-PIC-AT-004 |
|---|
Term
Description
Configuration
technical implementation of all the content and process conditions as defined by the Data Policy for Consent Agreement creation, reading, updating and deletion, as well as for providing all necessary actors with the required operations
Consent Agreement
is the agreement to be signed by the Individual and the Data Controller as prescribed by Data Policy, based on which the Data Providing System may transmit the data to the Data Consuming System for the purposes described in the Consent Agreement.
Consent Record
is created when an individual signs a consent agreement. It represents a signed consent agreement.
Consent Reference
a unique identifier used to locate and verify the validity of the Consent Agreement.
Data Providers
is a legal entity that stores and provides access to an Individual's data, which requires the Individual's consent for processing (outside of its primary purpose/location).
Data Consumers
is a legal entity that requires the Individual's data from the Data Providers according to the consent of the Individual.
Data Disclosure Agreements
a Data Disclosure Agreement (DDA) exists between two organisations where one organisation acts as a Data Provider and the other as a Data Consumer. The DDA captures how data is shared between the two organisations and what role and obligation each party has.
Data Policy
is a formal description of the purpose, nature and extent of consent-based Personal Data processing, covering the configuration needs by Data Providing System and Data Consuming System and the conditions defined by law.
Data Processing Auditor
is an entity (a person or an organisation) verifying the legitimacy of Personal Data processing by Data Controllers and Data Processors based on the Data Policies and performed tasks. The entity is not to be confused with a data policy auditor that is independent of the actors involved in the operations of consent management and can engage directly with the Consent BB service operator.
Delegate
the person giving consent (signing Consent Agreement); on behalf of the Individual,
Individual
is a person about whom the Personal Data is stored in an information system (a.k.a. “Data Subject”) and who agrees or not with the use of this data outside of its primary purpose/location.
Legal Entity
is an organisation (public or private) that has the rights and obligations to define standards for Personal Data processing. E.g. a public health authority
Personal Data
is any information that (a) can be used to identify the Individual to whom such information relates, or (b) is or might be directly or indirectly linked to the Individual (ISO(IEC 29100:2011)
Regulations
are broadly defined as rules followed by any system: could be laws, bylaws, norms or architectures that regulate a given system. The term and definition is inspired by Lessig’s modalities of regulation: https://lessig.org/images/resources/1999-Code.pdf
Identity Building Block
It is assumed the Consent Building Block has already obtained requisite access tokens.
Workflow Building Block
Manages the workflow and rules associated with requiring or not requiring consent to use Personal Data.
Scheduler Building Block
Provides an engine for time-based triggers to various events of an automated business process, which might also require consent.
Information Mediator Building Block
The information mediator Building Block provides a gateway for exchanging data related to consenting workflows; it also provides logs for auditing purposes.
Name
View agreements - Postpartum and infant care
Description
The use case implements the viewing and understanding consent agreements, data policies applied to Personal Data processing. This includes obtaining copies of the consent agreement.
Trigger (the event that triggers the use case)
The individual user wishes to view the agreements and policies associated with Personal Data usage
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The individual user logged into the healthcare application and have sufficient privileges to use the system
The user has previously registered and signed the consent agreement
The healthcare application has pre-configured consent agreements for the use of Personal Data
Data inputs
Login credentials
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
Individual user
The health-care provider application. (a computer system)
Optionally: a data intermediary or a data operator.
Normal Course (what happens if the event is triggered and the preconditions have been met)
The individual user invokes the view agreement workflow
Views all configured consent agreements
The user is able to download a copy of agreement
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Get data failure scenarios
Download option fails
The individual is able to withdraw consent or update existing consents as the next step of viewing all consent agreements at one place.
Data output
None
Post-Conditions (the success criteria)
The individual is able to view consent agreements that are signed or to be signed.
The individual is also able to download the signed agreement
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Identity BB (Required for acquiring authentication token)
Registries BB - stores the data agreement data,
Information Mediator BB - providing interfaces
Security BB - supervision
Name
Consent - Postpartum and infant care (Give consent)
Description
The use case allows an end-user to consent to fetch data from existing sources (possibly external to the application) or to manually fill in details during new mother registration.
In this option, the patient is doing a self-registration without any help of a healthcare assistant
Trigger (the event that triggers the use case)
During a registration process, the workflow BB assumes or identifies the need for consent (precondition).
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
UC-C-PIC-001 has defined and published the configuration for the registration workflow.
The individual is already registered into an identity management system (for example a population registry) that holds the user information, as required for consent.
The user has the authority to consent as the owner or delegate to fetch the record.
Data inputs
The unique identifier of the individual that can be verified/used across BBs. E.g. Social Security Number.
Service reference for which the consent is being sought
The consent agreement demonstrates the use of data for which the consent is being sought
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
A consenting individual
The healthcare system application
The data source provides the registration data or credentials for a given identity data.
Normal Course (what happens if the event is triggered and the preconditions have been met)
The healthcare application understands the need for consent via the consent agreement definition.
The individual is presented with the consent agreement together with the data policy for registration, requesting the data to be fetched from an external source, e.g. population register.
The individual agrees (consents / opt-in) to fetch the data. A consent record is created.
The data is fetched from the external source successfully.
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Individual cancels fetching the data.
Data output
A consent record is created in the registry.
Post-Conditions (the success criteria)
The registration is completed successfully importing data from a data provider.
Consent Status is registered and can be queried (i.e. made available to the consent mediator)
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Identity BB
Workflow BB - workflow management
Registries BB - Fetch the applicable data agreement
Information Mediator BB - providing interfaces
Security BB - supervision
Name
Consent - Postpartum and infant care (Give consent)
Description
The use case implements end-user to consent to fetch data from existing sources or to manually fill in details during new mother registration.
In this option, the patient is assisted by a healthcare assistant
Trigger (the event that triggers the use case)
Same as UC-C-PIC-I-002A
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
Same as UC-C-PIC-I-002A
Data inputs
The primary identity is key to the individual. E.g. Social Security Number by the healthcare assistant
Rest same as UC-C-PIC-I-002A
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
A healthcare assistant assisting in the registration process
Rest same as UC-C-PIC-I-002A
Normal Course (what happens if the event is triggered and the preconditions have been met)
The healthcare application understands the need for consent via the consent agreement definition. The healthcare assistant gets notified of the need for consent.
The individual is presented with the consent agreement together with the data policy for registration, requesting the data to be fetched from an external source, e.g. population register.
The individual agrees (consents / opt-in) to fetch the data. A consent record is created.
The data is fetched from the external source successfully.
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Individual cancels or opts out of fetching the data
Data output
Same as UC-C-PIC-I-002A
Post-Conditions (the success criteria)
The registration is completed successfully importing data from a data provider.
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Same as UC-C-PIC-I-002A
Name
Consent - Postpartum and infant care (Give consent)
Description
The use case implements end-user to consent to fetch data from existing sources or to manually fill in details during new mother registration.
In this option, the patient is using a physical or digital document or data card as a data source that is verifiable
Trigger (the event that triggers the use case)
During a registration process, the workflow BB identifies the need for consent.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
Same as UC-C-PIC-I-002A
Data inputs
Same as UC-C-PIC-I-002A
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
Same as UC-C-PIC-I-002A or UC-C-PIC-I-002B
Normal Course (what happens if the event is triggered and the preconditions have been met)
The healthcare application understands the need for consent via the consent agreement definition.
The individual is presented with the consent agreement together with the data policy for registration, requesting the data to be fetched from a verifiable document (physical or digital)
The individual uses the verifiable document, explicitly consenting to the use of data. A consent record is created.
The data is fetched from the data card (may use an external system as configured in the physical or digital card).
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Individual cancels fetching the data.
Data output
A consent record is created in the registry.
Post-Conditions (the success criteria)
The registration is completed successfully importing data from a data provider.
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Same as UC-C-PIC-I-002A
Name
Withdraw or update existing consent - Postpartum and infant care
Description
The use case implement the withdrawal or updating of existing signed consent agreements.
Trigger (the event that triggers the use case)
The individual user wishes to withdraw or update the existing consent agreement with regard to the use of Personal Data.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The individual user logged into the healthcare application and have sufficient privileges to use the system
The user has previously registered and signed the consent agreement(s).
The healthcare application has pre-configured consent agreements for the use of Personal Data
Data inputs
Login credentials
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
Individual user
The health-care provider application. (a computer system)
Optionally: a data intermediary or a data operator.
Normal Course (what happens if the event is triggered and the preconditions have been met)
The individual user invokes the view agreement use case (UC-C-PIC-I-001) and views all existing consent agreements
The individual user chooses the particular consent which needs to withdraw consent or update an earlier consent.
The individual user confirms the action
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Withdraw or update consent failure scenarios
Connection error scenarios
Data output
NA
Post-Conditions (the success criteria)
The individual is able to view consent agreements that are signed or to be signed.
The individual is able to withdraw consent or update existing consents.
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Identity BB (Required for acquiring authentication token)
Registries BB - stores the data agreement data,
Information Mediator BB - providing interfaces
Security BB - supervision
Name
Consent agreement change notification- Postpartum and infant care
Description
The use case implement the Consent agreement change notification for existing consent agreements
Trigger (the event that triggers the use case)
The individual user wishes to withdraw or update the existing consent agreement with regard to the use of Personal Data.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The individual user logged into the healthcare application and have sufficient privileges to use the system
The user has previously registered and signed the consent agreement(s).
The healthcare application has pre-configured consent agreements for the use of Personal Data
Data inputs
Login credentials
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
Individual user
The health-care provider application. (a computer system)
Optionally: a data intermediary or a data operator.
Normal Course (what happens if the event is triggered and the preconditions have been met)
The individual user invokes the view agreement use case (UC-C-PIC-I-001) and views all existing consent agreements
The individual user chooses the particular consent which needs to withdraw consent or update an earlier consent.
The individual user confirms the action
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Withdraw or update consent failure scenarios
Connection error scenarios
Data output
NA
Post-Conditions (the success criteria)
The individual is able to view consent agreements that are signed or to be signed.
The individual is able to withdraw consent or update existing consents.
Exceptions (error situations)
Related BBs (working groups related to that particular use case)
Identity BB (Required for acquiring authentication token)
Registries BB - stores the data agreement data,
Information Mediator BB - providing interfaces
Security BB - supervision
Name | Consent - Postpartum and infant care (Audit - MONITOR POLICY UPDATE) |
Description | The use case implements the tasks required to be performed when a Data Policy change occurs. This MAY require an update of the Consent Agreement and/or information to the Individual (jurisdiction dependent) |
Trigger (the event that triggers the use case) | The MONITOR POLICY UPDATE use case is triggered each time the Data Policy receives a modification. The Data Policy Auditor needs to identify consent records that require a modification of the consent agreement. |
Preconditions (list of conditions that MUST be met for the use case to be successful) | The use case assumes that the Data Policy Auditor is authorised to perform the audit. Therefore the Data Policy Auditor has all the necessary, but limited, access rights to access the information. This can be done either with a specific component of the Application that allows these access to a person outside the organisation/department owning the application or by an authorised employee of the organisation operating under the instruction of the Data Policy Auditor (whose legitimity is specified in the Audit Framework). The Organisation provides the Application Administrator with the new policy and the system updates to be done. This includes potential actions on existing consent records or communication to consentees. This use case assumes that the policy change has been processed by the organisation maintaining the system..
Same preconditions as UC-C-PIC-AT-001 AUDIT CONSENT
|
Data inputs |
And same data inputs as UC-C-PIC-AT-001 AUDIT CONSENT
|
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both) |
|
Normal Course (what happens if the event is triggered and the preconditions have been met) |
|
Alternative Course (links to other use cases in case there are different ways how to solve the same use case) | --- |
Data output | Audit files (incl. Supporting information) |
Post-Conditions (the success criteria) | Audit information available for further audit of the information system. |
Exceptions (error situations) | An escalation process is to be put in place if, for any reason, the Data Policy Auditor can not perform his work.. |
Related BBs (working groups related to that particular use case) | Same as UC-C-PIC-AT-001 Audit Consent |
Name | Consent - Postpartum and infant care (Audit - READ Consent status) |
Description | READ CONSENT STATUS - Viewing (reading, exporting) the Consent Agreements and relevant information from the Consent Records in a verifiable form |
Trigger (the event that triggers the use case) | For a given population of Individuals, an authorised Data Policy Auditor wants to read their Consent Record. |
Preconditions (list of conditions that MUST be met for the use case to be successful) | Application is configured. At least one Consent Record attached to a Consent Agreement for an Individual is present (ie. Consent BB is active). The use case assumes that the Data Policy Auditor is authorised to perform the audit. Therefore the Data Policy Auditor has all the necessary, but limited, access rights to access the information. This can be done either with a specific component of the Application that allows these access to a person outside the organisation/department owning the application or by an authorised employee of the organisation operating under the instruction of the Data Policy Auditor (whose legitimity is specified in the Audit Framework). |
Data inputs | The population of individuals for which the authorised Data Policy Auditor wants to read the status. |
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both) |
|
Normal Course (what happens if the event is triggered and the preconditions have been met) |
|
Alternative Course (links to other use cases in case there are different ways how to solve the same use case) | There is no Alternative Course of action. Should, for any reason, the Normal Course of action not be terminated successfully. The Data Policy Auditor MUST raise an audit finding. The Audit Framework is responsible to handle audit finding (not the application) |
Data output | Audit files (incl. Supporting information) that can be imported in the Data Policy Auditor’s system |
Post-Conditions (the success criteria) | Audit information available to the Data Policy Auditor for further audit of the Application. |
Exceptions (error situations) | An escalation process is to be put in place if, for any reason, the Data Policy Auditor can not perform his work.. |
Related BBs (working groups related to that particular use case) | Same as UC-C-PIC-AT-001 Audit Consent. |
Name | Consent - Postpartum and infant care (Audit - VERIFY Consent Integrity) |
Description | VERIFY CONSENT INTEGRITY - Ability to check the integrity of the signed agreements.
Important note: To verify the INTEGRITY, the Data Policy Auditor does not need to receive the INFORMATION in the Consent Record. For example, the names of the individual or any other personal or sensitive information do not need to be disclosed to the Data Policy Auditor for the purpose of Integrity verification. The cryptographic signature should be sufficient. Nevertheless, the auditor must receive sufficient supporting information to certify and record that this Consent Record for this agreement was signed and this time and not tempered with. The Auditor will record this information that may be used later in the audit process.nAccessing the content itself of is a different use case. This note helps to clarify a simple verification process that could be automated from a more indepth process where access to sensitive information
|
Trigger (the event that triggers the use case) | For a given Consent Record, an authorised Data Policy Auditor wants to verify the integrity of the consent.. |
Preconditions (list of conditions that MUST be met for the use case to be successful) | Application is configured. The Consent Record under investigation is already in the Application. The Consent BB is active. The use case assumes that the Data Policy Auditor is authorised to perform the audit. Therefore the Data Policy Auditor has all the necessary, but limited, access rights to access the information. This can be done either with a specific component of the Application that allows these access to a person outside the organisation/department owning the application or by an authorised employee of the organisation operating under the instruction of the Data Policy Auditor (whose legitimity is specified in the Audit Framework). |
Data inputs | The Consent Record for which the authorised Data Policy Auditor wants to verify the integrity.. |
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both) |
|
Normal Course (what happens if the event is triggered and the preconditions have been met) |
|
Alternative Course (links to other use cases in case there are different ways how to solve the same use case) | There is no Alternative Course of action. Should, for any reason, the Normal Course of action not be terminated successfully. The Data Policy Auditor MUST raise an audit finding. The Audit Framework is responsible to handle audit finding (not the application) |
Data output | Audit files (incl. Supporting information) that can be imported in the Data Policy Auditor’s system |
Post-Conditions (the success criteria) | Audit information available to the Data Policy Auditor for further audit of the Application. |
Exceptions (error situations) | An escalation process is to be put in place if, for any reason, the Data Policy Auditor can not perform his work.. |
Related BBs (working groups related to that particular use case) | Same as UC-C-PIC-AT-001 Audit Consent. |
Name | Consent - Postpartum and infant care (Audit - AUDIT CONSENT) |
Description | The use case implements the tasks required to track the opt-in/out consent by an Individual and formalised in a Consent Agreement. This results in a new entry in a registry that will record the Individual, his/her decision and the specific Consent Agreement as well as other necessary meta-data to subsequently manage the consent (e.g. dates, Consent Agreement version, …). |
Trigger (the event that triggers the use case) | The AUDIT CONSENT use case is triggered each time a Consent Record is modified.
|
Preconditions (list of conditions that MUST be met in order for the use case to be successful) | The use case assumes that the Data Policy Auditor is authorised to perform the audit. Therefore the Data Policy Auditor has all the necessary, but limited, access rights to access the information. This can be done either with a specific component of the Application that allows these access to a person outside the organisation/department owning the application or by an authorised employee of the organisation operating under the instruction of the Data Policy Auditor (whose legitimity is specified in the Audit Framework).
|
Data inputs |
|
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both) |
Optionally: a data intermediary or a data operator. |
Normal Course (what happens if the event is triggered and the preconditions have been met)
(See Sequence diagrams below) |
|
Alternative Course (links to other use cases in case there are different ways how to solve the same use case) |
|
Data output |
|
Post-Conditions (the success criteria) |
|
Exceptions (error situations) | An escalation process is to be put in place if, for any reason, the Data Policy Auditor can not perform his work.. |
Related BBs (working groups related to that particular use case) |
|
Following are the use-case specifications required by the organisation IT administrators for updating Data Policies required for an identified Consent Agreements (within postpartum and infant care)
UC-C-PIC-A-001: Postpartum and infant care (Configuration CREATE)
UC-C-PIC-A-002: Postpartum and infant care (Configuration UPDATE)
UC-C-PIC-A-003: Postpartum and infant care (Configuration READ)
UC-C-PIC-A-004: Postpartum and infant care (Configuration DELETE)
UC-C-PIC-A-005: Postpartum and infant care (Configuration NOTIFICATIONS)
The following sequence diagrams details the role of the Independent Authority and the DPIA (Data Protection Impact Assessment) as the document upon which the postpartum infant care program can rely to parametrise the healthcare application for interacting with the Consent BB.
ID
UC-C-PIC-001
Name
Postpartum and infant care (Configuration CREATE)
Description
The use case implements configuration of a consent agreement towards infant care use case scenarios. This results in a saved configuration to be issued to all mothers requiring infant care.
Trigger (the event that triggers the use case)
The (healthcare) application admin/user wishes to configure the policies associated with the data usage.
Any change in the pre-condition that requires a re-configuration.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The (healthcare) application admin/user is logged into the system and has sufficient privileges to use the system
A healthcare policy exists, and is based on existing data laws for healthcare.
Assumption: consent is needed for pulling data from another system of the mother needing care.
Data inputs
Existing data policies relevant to the healthcare scenario
Any legal information, standards.
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The (healthcare) application admin/user configures the data usage policy. (a person, IT admin)
The health-care provider application. (a computer system)
DPO, Auditors (A person, or an independent authority)
Optionally: a data intermediary or a data operator.
Normal Course (what happens if the event is triggered and the preconditions have been met)
The healthcare application user is able to invoke the configuration workflow.
The healthcare user uses the existing policy relevant to registering for postpartum and infant care. This could be signed off by the organisation's DPO, for example.
The data required are:
Usage purpose
Data policies and rules
Define what data is being collected
The configuration is saved.
Once the DPO approves, the configuration is published towards the end-use case. I.e. registration system.
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Data configuration error scenarios
DPO disapproves and the configuration is re-submitted for review and approval.
Data output
The consent configuration data
Post-Conditions (the success criteria)
The data usage policy is saved in the system and is available for the month to consent to during the registration process.
The system is now configured and ready for collecting user consent during a registration workflow.
Exceptions (error situations)
(TBD - Should align with other error scenarios.)
Related BBs (working groups related to that particular use case)
Identity BB (Required for acquiring authentication token)
Workflow BB - workflow management
Information Mediator BB - providing interfaces
Security BB - supervision
ID
UC-C-PIC-002
Name
Postpartum and infant care (Configuration UPDATE)
Description
Here, an organisation Administrator updates Consent Agreement based on the Data Policy requirements..
Trigger (the event that triggers the use case)
The (healthcare) application admin/user wishes to configure the policies associated with the data usage.
Any change in the pre-condition that requires a re-configuration.
Preconditions (list of conditions that MUST be met in order for the use case to be successful)
The (healthcare) application admin/user is logged into the system and has sufficient privileges to use the system
A healthcare policy exists, and is based on existing data laws for healthcare.
Assumption: consent is needed for pulling data from another system of the mother needing care.
Data inputs
Existing data policies relevant to the healthcare scenario
Any legal information, standards.
Actors (a person, a company or organisation, a computer program, or a computer system - hardware, software, or both)
The (healthcare) application admin/user configures the data usage policy. (a person, IT admin)
The health-care provider application. (a computer system)
DPO, Auditors (A person, or an independent authority)
Optionally: a data intermediary or a data operator.
Normal Course (what happens if the event is triggered and the preconditions have been met)
TBD
Alternative Course (links to other use cases in case there are different ways how to solve the same use case)
Data configuration error scenarios
DPO disapproves and the configuration is re-submitted for review and approval.
Data output
Updated consent configuration data, Revision
Post-Conditions (the success criteria)
The data usage policy is saved in the system and is available for the month to consent to during the registration process.
The system is now configured and ready for collecting user consent during a registration workflow.
Exceptions (error situations)
(TBD - Should align with other error scenarios.)
Related BBs (working groups related to that particular use case)
Identity BB (Required for acquiring authentication token)
Workflow BB - workflow management
Registries BB - stores the data agreement data,
Information Mediator BB - providing interfaces
Security BB - supervision
DELETE - Cascading delete operation for Right To Be Forgotten, deletes all Consent Records that shall not be retained and have a "forgettable" Agreement. May also delete an unsigned Consent Record, for instance in cases where the user exits the signing process. Individual ID supplied as HTTP header.
READ - Fetch an Individual in the Consent system
Unique ID of an object
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""LIST - lists individuals in the system
Requested index for start of resources to be provided in response requested by client
Requested number of resources to be provided in response requested by client
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""CREATE - Creates an Individual in the Consent system
Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""UPDATE - Updates an Individual in the Consent system
Unique ID of an object
Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""LIST - returns the current Policy
Unique ID of an object
Requested index for start of resources to be provided in response requested by client
Requested number of resources to be provided in response requested by client
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""LIST - Fetches list of readable Policy objects
An object with id revisionId
Requested index for start of resources to be provided in response requested by client
Requested number of resources to be provided in response requested by client
A list of Policy objects readable for the current session's credentials.
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""READ - fetches the latest version of a Policy and the presented revisionId of an associated Agreement
Unique ID of an object
An object with id revisionId
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""READ - get a Policy object + latest Revision. If a PolicyFilter is supplied and contains a revision_id, then this specific revision is returned.
Unique ID of an object
An object with id revisionId
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""UPDATE - Updates an existing Policy object, returning the updated version and a new revision. Updating a Policy does not affect existing references in Agreement, the new revision should be specified for Agreement.
Unique ID of an object
A policy governs data and Agreement in the realm of an organisation that is refered to as "data controller" (GDPR) and owner of referencing Agreements.
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""CREATE - Creates a new Policy object and returns the new object and a PolicyRevision
A policy governs data and Agreement in the realm of an organisation that is refered to as "data controller" (GDPR) and owner of referencing Agreements.
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""A set consisting of the new Policy object created, together with the initial Revision object.
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""DELETE - Deletes an existing Policy object, returning the updated version and a new revision. Deleting a Policy is not possible if it's associated with active Agreement.
Unique ID of an object
""This was previously called "schema" but for technical reasons should be called "schema_name"
""The PK of the object that was serialized.
""Indicates that object_id was left blank in serialized_snapshot when calculating serialized_hash. object_id may be subsequently filled in.
""Revisioned data (serialized as JSON) as a dict {object_data: {...}, schema_name: ..., object_id: ..., signed_without_object_id: ..., timestamp: ..., authorized_by_individual: ..., authorized_by_other: ...}. It contains all the fields of the schema except id, successor, predessor_hash and predecessor_signature.
""Hash of serialized_snapshot (SHA-1)
""Timestamp of when revisioning happened
""Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""Reference to an admin user that has created this revision
""A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
""This was previously called "schema" but for technical reasons should be called "schema_name"
""The PK of the object that was serialized.
""Indicates that object_id was left blank in serialized_snapshot when calculating serialized_hash. object_id may be subsequently filled in.
""Revisioned data (serialized as JSON) as a dict {object_data: {...}, schema_name: ..., object_id: ..., signed_without_object_id: ..., timestamp: ..., authorized_by_individual: ..., authorized_by_other: ...}. It contains all the fields of the schema except id, successor, predessor_hash and predecessor_signature.
""Hash of serialized_snapshot (SHA-1)
""Timestamp of when revisioning happened
""Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""Reference to an admin user that has created this revision
""A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
Tamper-resistent artifact from previous record, copied from serialized_hash
""Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)
""Tamper-resistent artifact from previous record, copied from serialized_hash
""Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)
""READ
Unique ID of an object
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a ConsentRecord that is not yet stored in the database and only exist in transit. Draft ConsentRecords do not have a Revision, but if paired up with a Signature, a valid Revision should be generated.
""An agreement contains the specification of a single purpose that can be consented to. An Agreement is universal and can be consented to by many individuals through a ConsentRecord
""The version of this specification to which a receipt conforms
""Details of a data controller.
""Name of data controller (may be omitted if no data involved)
""URL of data controller (may be omitted if no data involved)
""A policy governs data and Agreement in the realm of an organisation that is refered to as "data controller" (GDPR) and owner of referencing Agreements.
""Name of the policy
""Version of the policy
""Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
""""""""""""TBD: Models the purpose of an agreement
""Name of purpose
""Description of purpose
""In order to sign an Agreement, this relation needs to have a cryptopgraphic hash of the JSON serialized data to be included in the Signature payload of the Agreement. Hashes are collected as the hex representation of the SHA-1 sum of all UTF8 encoded string versions of the JSON representation of data. SHA1(json_serialized_data)
""Lawful basis of the agreement - consent / legal_obligation / contract / vital_interest / public_task / legitimate_interest
""null/data_source/data_using_service
""Data Protection Impact Assessment
""A generic signature contains a cryptographic hash of some value, together with a signature created by some private key in another system. Required signing methods: Revision object or another Signature object.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
""The final payload that is signed, constructed as a JSON serialization of fields {verificiation_payload: ..., verification_payload_hash: ..., verification_method: ..., verification_artifact: ..., verification_signed_by: ..., verification_jws_header, timestamp: ..., signed_without_object_reference: ..., object_type: ..., object_reference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the object_reference should be omitted from the payload but filled in afterwards.
""Signature of payload hash, the format of the signature should be specified by either verification_method or verification_jws_header
""A well-known string denoting which method is used. Valid values: . We might expand this with a relation to which verification methods that are supported. There may be a minimal set of supported methods necessary.
""Internally generated serialized version of the data referenced by object_type and object_reference - by extracting and serializing their data as JSON.
""Internally generated cryptographic hash of the value to be signed, i.e. the value of verification_payload
""A verification artifact in the form of a scanned object, image, signature etc.
""Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
""DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
""Alternative to the verification_method, verification_hash and verification_signature, give a JWS serialized object (RFC7515)
""Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
""Indicates that object_reference was left blank in the serialized version that was signed.
""Name of the schema model that object_reference points to. Values: "signature" or "revision"
""A symmetric relation / back reference to the object_type that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
""Agreement is active and new ConsentRecords can be created.
""Consent Record may be deleted when consent is withdrawn, as its existence is not necessary for auditability.
""An agreement contains the specification of a single purpose that can be consented to. An Agreement is universal and can be consented to by many individuals through a ConsentRecord
TBD: Models the valid lifecycle states of an Agreement
""Draft / Complete
""A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
""This was previously called "schema" but for technical reasons should be called "schema_name"
""The PK of the object that was serialized.
""Indicates that object_id was left blank in serialized_snapshot when calculating serialized_hash. object_id may be subsequently filled in.
""Revisioned data (serialized as JSON) as a dict {object_data: {...}, schema_name: ..., object_id: ..., signed_without_object_id: ..., timestamp: ..., authorized_by_individual: ..., authorized_by_other: ...}. It contains all the fields of the schema except id, successor, predessor_hash and predecessor_signature.
""Hash of serialized_snapshot (SHA-1)
""Timestamp of when revisioning happened
""Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""Reference to an admin user that has created this revision
""A generic revision model captures the serialized contents of any shema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
Tamper-resistent artifact from previous record, copied from serialized_hash
""Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)
""Copy of the revision hash. The hash is the included in the signature and ensures against tampering with the original agreement.
""Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). An Individual instance of this model is not to be mistaken with a unique natural individual. It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
The unique ID of an Individual row.
""Reference to another foundational/functional ID, which is likely PII
""External id type specifier. A string. For instance "email" or "foundational id". Can be used in later queries.
""This could be an FK, but for now we do not have a mapping of identity providers. IDBB may have more requirements.
""True: The individual has positively opted in. False: The individual has explicitly said no (or withdrawn a previous consent).
""The state field is used to record state changes after-the-fact. It is maintained by the Consent BB itself. Valid states: unsigned/pending more signatures/signed
""A generic signature contains a cryptographic hash of some value, together with a signature created by some private key in another system. Required signing methods: Revision object or another Signature object.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
""The final payload that is signed, constructed as a JSON serialization of fields {verificiation_payload: ..., verification_payload_hash: ..., verification_method: ..., verification_artifact: ..., verification_signed_by: ..., verification_jws_header, timestamp: ..., signed_without_object_reference: ..., object_type: ..., object_reference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the object_reference should be omitted from the payload but filled in afterwards.
""Signature of payload hash, the format of the signature should be specified by either verification_method or verification_jws_header
""A well-known string denoting which method is used. Valid values: . We might expand this with a relation to which verification methods that are supported. There may be a minimal set of supported methods necessary.
""Internally generated serialized version of the data referenced by object_type and object_reference - by extracting and serializing their data as JSON.
""Internally generated cryptographic hash of the value to be signed, i.e. the value of verification_payload
""A verification artifact in the form of a scanned object, image, signature etc.
""Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
""DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
""Alternative to the verification_method, verification_hash and verification_signature, give a JWS serialized object (RFC7515)
""Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
""Indicates that object_reference was left blank in the serialized version that was signed.
""Name of the schema model that object_reference points to. Values: "signature" or "revision"
""A symmetric relation / back reference to the object_type that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
""
