It is highly problematic to expose sensitive data to the Internet. The service hosting the sensitive data, which provides access to files or service, needs to be compromised only for a short amount of time, to have all the data leaked. This is often caused by configuration mistakes or by vulnerabilities being present in the used technology stack.
We cannot afford to have leaks on personal-identifiable data in data vaults. To raise the bar on making attacks difficult and reducing the chance of leakage of information, we introduce the Guardian as an extra security layer to protect services in an Aqua domain from attacks.
The Guardian is a software which manages the boundaries of your Aqua domain. Guardians are used to connect to secure transport networks (HTTPS, Matrix Network, DIDComm) and publishing networks (e.g. Swarm.eth). The Guardian is used to build trusted connections to other Guardians via trusted transport layers to exchange data with them. It also manages all connections to services within the Aqua domain.
The goal is to secure all services behind the Guardian from attacks and unauthorized accesses. And to keep the data vault and its data private and safe, while enabling the ability to exchange data with the other Guardians.
Enforcement is handled on each connection and each data set so that services behind the Guardian are never directly exposed. This makes the Guardian the most security sensitive component in the Aqua reference implementation, as we expect the Guardian to handle all the incoming and outgoing traffics. The Guardian enjoys additional attention and effort to be up to its task by hardening it and applying security best practices to ensure that it is fulfilling its security promise to keep services behind the Guardian safe.
Every transaction leaving or wanting to enter your domain will be supervised and checked by the Guardian. The core functionality of the Guardian is a library to verify the Aqua Protocol. Only if the verification succeeds may additional steps be introduced to make decisions on how the data is handled.
This allows the Guardian to read and understand Aqua verified data. This allows for the implementation of a wide set of behavioral rules and offers the opportunity to create various 'Smart contract' languages on top of it.
The Guardian verifies a file, reads its contents and checks its permissions to classify if an action is considered legal or illegal, permitted or denied. Basic functionality for a Guardian can be compared with a traditional firewall, or a application firewall but is much more sophisticated to manage access on the data-level.
Proving ownership over a domain by signing the domain ID with an self-issued identity claim which is also registered in a claim registry to ensure nobody claims to have owned that domain before by manipulating the digital clock and faking an earlier owner-ship claim over the domain.
Permission agreements are contracts which represent the terms and conditions under which files and/or services are shared with other accounts and/or their digital domains.
By nature, those Permission agreements will be compiled through pages and stored as files. To form an agreement, the other party must be notified about new resources as they become available. For example, when we share a page with another account. To complete a permission agreement, the counter party has to sign the permission agreement or reject it. If the permission agreement is signed, the other party enters a contractual relationship in which they will be liable for any agreement violates executed from their digital domain.
The domain handshake establishes trust between two Aqua domains. For this we have Alice and Bob who want to establish trust between their domains. They both have a Guardian in place to protect their data vaults.
- Alice: Create access contract: I <Alice_account> want to connect from my <domain_id> to a <domain_id> controlled by <Bobs_account> with my <alice_domain_id> via the following channel: DNS/HTTPS via <alice_Guardian.domain.com>.
- Alice: sign contract
- Alice: SEND contract send the page via 'mail' / 'matrix' whatever to the remote PKC instance.
- Bob: veries the contract contract and imports it
- Bob: extend contract: I <bobs_acocunt> connect my PKC <bobs_domain_id> to your PKC <Alice_domain_id> via my Guardian_endpoint <bobs_guardian.domain2.com>.
- Bob: sign extended contract: Bob uses his wallet to sign his extended contract.
- Bob: send extended contract TO Alice: Bob sends his Contract to his Guardian.
- Bob's Guardian: Verifies and sends the contract to Alice Guardian.
- Alice Guardian: Guardian verifies all data Sends OK back to Bob's Guardian Sends Updates contract into Alice PKC Waits for Bob's Guardian to request available pages
- Bob's Guardian requests a list of pages: ' What pages do you share with me?'
- Alice Guardian: Returns list of accessible resources for Bob
Target: Sharing a file with another account. Using two Aqua data vaults with their two Guardians to manage access to them. We assume the Guardians already have executed a handshake to enter a trusted relationship. We also assume, that the file should underlay access basedon account restrictions and domain restrictions.
Example 1: Sharing a file without additional constraints with another account.
Alice wants to share her page 'My secret research' with Bob. Their Guardians have already formed a trusted connection. What Alice needs to do now is to add a sub-page with an immutable link under the 'My secret research' page and define access. To be able to define access Alice needs to have a claim over the ownership over the domain she is sharing from.
Alice creates an Access Permission for the whole page or for a single revision by creating a page with the following syntax:
-
<genesis_hash>:access_contract -
To give access to the whole page with all it's revisions.
-
<revision_hash>:access_contract -
To give access to a specific revision.
Content of the page:
I Alice <Alice-account> give access to Bob <Bob-account>
- option 1: to the whole page including its history
<genesis_hash> - option 2: to the following revision <revision_hash>'My secret research'
Additional one-sided conditions:
- This access contract expires in 7 days
This contract will come into place with my <Alice-account> signature.
The Guardian will react to a specific syntax of the pages holding the contracts, agreements and access rights to adjust his network access rights accordingly to it. Alice-Guardian will respond to the question what resources are shared by Bobs-Guardian with the answer that there is a new page available according to the access contract which now gives Bobs-Guardian the ability to query the content of 'My secure research' from Alice according to the contract. Depending on Bobs-Guardian setting, the Guardian might automatically load the resource and forward it into the post-box of Bobs Data Vault.
Example 2: Sharing a file with constraints forming a contract to do so.
Same as 1 expect that for the contract to come into place, Bob needs to sign the contract from Alice containing additional constraints.
Content of the page:
I Alice <alice-account> give access to Bob <bob-account>
- option 1: to the whole page including its history
<genesis_hash> - option 2: to the following revision
<revision_hash>of 'My secret research'
Under the following conditions:
- Do not share outside your domain <Bobs-domain_id>
- Do not share with anybody else (Bobs domain can't have another account registered to it, if there is an account registered the Guardian of Bob will say that Bobs domain does not fulfill the requirements to establish this contract.
- Do not modify it.
- Delete it after 7 days.
For this contract to be valid, signatures of first Alice and then Bob need to be present. This means, after Alice signed the access contract, the contract is a new available resource to Bob to be loaded. Bob can now sign the resource in his domain and return the contract. Leading to the contract send back to Alice domain and being updated there. Bob now gets access to 'My secret research' which has been updated as well, to contain via an immutable link the access contract.
Permission Templates, Complex Permissions (Groups and more)
It is possible to apply complex permissions based on templates, or and connecting multiple access contracts by using
- instead of this syntax
<genesis_hash>:permission_agreement - the following the syntax
<genesis_hash>:<genesis_hash-2>in which the<genesis_hash-2>contains a list of sub-pages with access contracts which can be used to apply access via permission-objects which are represented by the<genesis_hash-2>page object.
- Alice wants to
- If the user wants to propose changes to the page, he will send an updated PAGE FILE to the OWNER of the PAGE.
- The owner can decide to ACCEPT the changes. Or to include the changes in the HISTORY File, but not COMMIT them. Or to NOT include the update of the PAGE, and disregard it.
The Guardian daemon checks if there is a digital contract present in his domain. Those contracts set permissions for allowing a counter party to access a service or resource (such as a file or a page, or a revision). It is also defining the constraints under which permissions access is given. In this case it requires the digital signature of the receiving party for the agreement to come into place and be valid.
Guardians have administrative access to the services they manage. Therefore they can supervise the activities of services and use them as triggers to e.g. provide access according to a set permission without additional user action.
APIs
- System-API to control a service via a service specific library. Each
services will have their own control-library and control API to
create an abstraction layer which allows for a unified control logic
in the Guardian.
- E.g. an account is allowed to access a service
- E.g. a resource is shared with an account
- E.g. a trust relationship between two services is established (based on an agreement between two accounts) to exchange data
- Implementation Specific PKC: All interactions for system
interaction with MediaWiki / PKC
- Execute Actions: Move, Update, Edit, Delete Pages
- Request send to the Guardian: Verify a specific page or a list of pages
- Data-API to retrieve Aqua-Data between a service and the
Guardian, or between two Guardians.
- Send data to import API
- Read data via export API
-
Implementation Specific PKC: Read special Pages used to give access e.g. Data Usage Agreements, Permission Agreements
Aqua Verification Library to be able to verify incoming and outgoing data
-
- implementation of the 'external-verifier' in e.g. GO, Typescript or Javascript (current)
- Account-Registry (Holding the list of trusted keys and the
relationship between them)
- This includes defined 'trusted accounts'
- Session-Handler/Registry (Acts like Stateful-Firewall on the page-object level to mange imports / exports). The Guardian verifies incoming and outgoing data and constructs sessions based on it.
- Guardian Policies: Are sets of rules followed and enforced by the
Guardian. This includes set of rules used to protect the domain from
unauthorized operations and access. Part of that are page access
permissions which are managed by the Data Usage
Agrement.
<domain_id><account><genesis_hash><revision_hash>:<domain_id><account><genesis_hash><revision_hash>
- Transport Layer API's / Sub-Modules for connectivity to distributed
services
- The Guardian-to-Guardian communication handler (via DNS/HTTPS transport)
- Ethereum Integration, Ethereum Handler (As a witness Network)
- Matrix Integration, Matrix Handler (As a restrictive/ permissioned transport layer)
- Swarm Integration, Swarm Handler (As a publishing network)
Giving access to pages with one-time passwords and signatures:
If you want to give somebody access to a page without ... continue.