Key Sharing¶

This guide introduces concepts of sharing keys with Blind Insight. This will cover the way data ownership and data requesting works by way of specialized "Data Owner" and "Data Requester" roles.

Prerequisites¶

To use key-sharing a user must register a PGP Identity with Blind Insight.

This is done using the Blind Proxy by running blind identity create:

blind identity create

A new PGP identity consisting of a public/private key pair will be generated. A unique device_id will be generated for the machine on which the Blind Proxy was used to uniquely identify the identity & device. The private key for this identity will be automatically stored in your local system keyring. The public key and device_id will be registered with the user's profile on the Blind Insight service.

To view your PGP keys you may do so by running blind keyring inspect:

blind keyring inspect

The Basics¶

• Every time a Schema is created, two teams are created: one each for "Data Owners" and "Data Requesters".
• The user who creates the Schema is automatically added to the "Data Owners" Team for that Schema.
• Each team has a Grant assigned to it with field-level key permissions.
• Upon adding a user to a Team, a Request is created for each field on the schema to which the Team has been Granted access.

The Data Owners Team:

• Has access to all keys including the query key and all field-level keys
• Has access to share keys for this Schema (can_share_keys=True is set), so that members of this Team may share keys with other users have been given access to the Schema
• Has access to encrypt/decrypt fields
• Has access to perform encrypted searches

The Data Requesters Team:

• Has access to the query key for the schema
• Has access to only perform encrypted searches

Data Model¶

Teams¶

Teams are groups of users that have access to a Schema. Each Team has at least one Grant that defines the access permissions for the Team.

To be added to a Team a user must be a member of the same Organization as the Schema to which the Team has access, and the user must have an Identity registered with Blind Insight.

Grants¶

Grants are the access permissions for a Team. They define the fields on a Schema to which a Team has access.

A Grant is created when a Schema is created. It is assigned to the Team that is created for the Schema.

A Grant is created with the following permissions:

• Specific field access permissions either for the query key or specific field-level keys
• Access to share keys for this Schema (can_share_keys=True is set), so that members of this Team may share keys with other users

Requests¶

Requests are created when a User is added to a Team. They are used to request access to the keys for the Schema to which the Team has access.

Requests can be fulfilled by any team member that has can_share_keys=True for the Grant to which the Request is associated.

Materials¶

Materials are the keys that are shared between Teams. They are created when a Request is fulfilled by a team member with can_share_keys=True.

Materials must be uploaded to the Material API to be made available to the user that requested the key.

Materials may be downloaded by the user holding the Identity that requested the key.

Key Sharing Workflow¶

The following steps describe the workflow for sharing keys. For this the users Bob (data owner) and Alice (data requester) will be used.

• Bob and Alice are members of the "ACME" Organization
• The Dataset called "People" already exists
• Bob creates a new Schema called "Person" in the "People" Dataset
• Data Owner/Requester Teams are created
• "People Data Owners" has a Grant with access to all fields (Person.*) and can_share_keys=True
• "People Data Requesters" has a Grant with access to the Person.__query field (query key) and can_share_keys=False
• Bob is automatically added to the "People Data Owners" Team
• Bob wants Alice to be a data requester and adds Alice to the "People Data Requesters" Team
• Upon being added to "People Data Requesters" a Request is created for each field in each Grant assigned to the team
• One Request will be created for each registered Identity for Alice
• Bob will then be able to review outstanding key Requests by running blind request list
• Bob can fulfill requests using blind request fulfill (TODO: this is currently called blind request update)
• Upon fulfilling a request a Material object is made and linked to the Request

How Material works

• Schema/field
• Requested key
• Proof (random 32-byte string)
• Proof is encrypted with requested key
• Entire payload is then encrypted with the user's public key
• Payload is uploaded to Blind Insight API, and can only be retrieved by the user whose identity matches the Material
• Proof is included in the upload but cannot be seen. Only the recipient who can download, decrypt the payload, extract the proof and the key, decrypt the proof will have access to the proof.
• Upon successful proof, the requested key is stored in the local keyring as a "key override"
• The proof is then sent back to the Material API to assert that the key has been successfully received
• Key overrides may be managed using blind material overrides

Blind Request Workflow¶

The blind request command allows you to manage key requests in the Blind Insight system.

Available Request Subcommands¶

1. Get a request
2. List requests
3. Fulfill requests

1. Get a Request¶

To retrieve a specific request:

blind request get --id <request_id>

This command fetches the details of a single request identified by its ID.

2. List Requests¶

To list all requests:

blind request list

By default, this command lists only outstanding requests (those that haven't been shared yet).

To list all requests, including those that have already been shared:

blind request list --all

3. Fulfill Requests¶

To fulfill requests by sharing keys:

blind request fulfill --id <request_id>

This command fulfills a single request identified by its ID.

To fulfill all outstanding requests:

blind request fulfill --all

When fulfilling requests, the system will:

1. Fetch the primary identity of the person fulfilling the request.
2. Prepare and encrypt material for each request.
3. Upload the encrypted material to the Blind Insight API.

Blind Material Workflow¶

The blind material command allows you to manage key material in the Blind Insight system.

Available Material Subcommands¶

1. Get material
2. List materials
3. Receive material
4. Manage overrides

1. Get Material¶

To retrieve a specific material:

blind material get --id <material_id>

This command fetches the details of a single material identified by its ID.

2. List Materials¶

To list all materials:

blind material list

You can filter the list by material ID or request ID:

blind material list --id <material_id>
blind material list --request <request_id>

3. Receive Material¶

To receive and process material for a specific request:

blind material receive --request <request_id>

To receive and process all outstanding materials:

blind material receive --all

When receiving material, the system will:

1. Decrypt the material payload.
2. Extract and decode the key from the payload.
3. Decrypt the proof using the key.
4. Submit the material proof to the API.
5. Install they key override in the local keyring

4. Manage Overrides¶

To list material overrides:

blind material overrides list

These workflows allow users to manage key requests and materials securely through the Blind Insight CLI, facilitating the process of sharing and receiving encrypted data.