Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shamir deletion specification - server side #7609

Merged
merged 3 commits into from
Jun 25, 2024
Merged

Shamir deletion specification - server side #7609

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
df46490
Shamir deletion certificate rfc update.
AureliaDolo Jun 17, 2024
27453b5
Typos.
AureliaDolo Jun 20, 2024
7bd5353
Shamir deletion rfc clean up.
AureliaDolo Jun 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 139 additions & 20 deletions docs/rfcs/1000-shamir-based-recovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ To use the Shamir recovery:
secret `SK` and decrypt `SK(alice@shamir1)`.
6) Alice uses `alice@shamir1` to re-create a new device (the recovered device).

## 1 - Create & update a Shamir recovery setup
## 1 - Create a Shamir recovery setup

Authenticated API:

Expand All @@ -102,8 +102,7 @@ Authenticated API:
"fields": [
{
"name": "setup",
// Set to `None` to clear previous Shamir recovery setup
"type": "RequiredOption<ShamirRecoverySetup>"
"type": "ShamirRecoverySetup"
}
]
},
Expand Down Expand Up @@ -140,9 +139,10 @@ Authenticated API:
"status": "missing_share_for_recipient"
},
{
// Future evolution 1: Shamir recovery has already been setup, should ask your admin to reset it first !
"status": "shamir_setup_already_exists"
// Shamir recovery has already been setup
"status": "shamir_setup_already_exists",
},

{
// Returned if the timestamp in the certificate is too far away compared
// to server clock.
Expand Down Expand Up @@ -225,10 +225,12 @@ Consistency between `brief` and `shares` must be checked by the Parsec server:
- the recipients and their shares must be the same.
- the certificates datetimes & authors must be the same.

> **_Future evolution 2:_** Check the Shamir recovery setup against some
> **_Future evolution 1:_** Check the Shamir recovery setup against some
> organization-specific rules (e.g. the number of shares, the recipient's
> profiles, max number of share per recipient, etc.). See "Bonus" section below.

To update the setup, the previous setup must be deleted first.

And the related certificates:

```json5
Expand Down Expand Up @@ -704,11 +706,9 @@ The claimer gets access to `reveal_token` and `data_key`, it can then retrieve `
Then `ciphered_data` can be decrypted with `data_key`. From then on, the recovery works
just like the recovery device system (see `parsec core import_recovery_device` CLI).

## Bonus

### **Future evolution 1**: Only Admin can clear Shamir recovery
## 4 - Delete a shamir setup

Authenticated API, `organization_config`:
Authenticated API:

```json5
[
Expand All @@ -717,30 +717,136 @@ Authenticated API, `organization_config`:
4
],
"req": {
"cmd": "organization_config"
"cmd": "shamir_recovery_delete_setup",
"fields": [
{
"name": "certificate",
// Contains a ShamirRecoveryDeletionCertificate
"type": "bytes"
}
]
},
"reps": [
{
"status": "ok",
"status": "ok"
},
{
// Cannot deserialize data into the expected certificate
"status": "invalid_data"
},
{
// Share recipients lists are incoherent
"status": "incoherent_date"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Share recipients are the only not identifying data that we have in the deletion certificate to check. Maybe we could include more data from the brief to ensure coherence. I'm not sure how much it's needed though

},
{
// There is already a deletion certificate for the same setup
"status": "shamir_setup_already_deleted",
"fields": [
{
"name": "last_shamir_deletion_certificate_timestamp",
"type": "DateTime"
}

]
},
{
// Nothing to delete, ie no setup was found with the same (author_user_id, timestamp)
"status": "shamir_setup_not_found"
},
{
// Returned if the timestamp in the certificate is too far away compared
// to server clock.
"status": "timestamp_out_of_ballpark",
"fields": [
{
"name": "shamir_recovery_clear_strategy",
// Allowed values:
// - `ADMINS_ONLY`
// - `ADMINS_AND_SELF`
"name": "ballpark_client_early_offset",
"type": "Float"
},
// <------------ Already existing options omitted --------->
{
"name": "ballpark_client_late_offset",
"type": "Float"
},
{
"name": "server_timestamp",
"type": "DateTime"
},
{
"name": "client_timestamp",
"type": "DateTime"
}
]
},
{
"status": "not_found"
// Returned if another certificate or vlob in the server has a timestamp
// posterior or equal to our current one.
"status": "require_greater_timestamp",
"fields": [
{
"name": "strictly_greater_than",
"type": "DateTime"
}
]
}
]
],
}
]
```
The deletion certificate

```json5
{
"label": "ShamirRecoveryDeletionCertificate",
"type": "shamir_recovery_deletion_certificate",
"other_fields": [
{
// certificate author
"name": "author",
"type": "DeviceID"
},
{
"name": "timestamp",
"type": "DateTime"
},
{
"name": "setup_to_delete_timestamp",
"type": "DateTime"
},
// User here must be the one owning the device used as author
// (i.e. a user can only remove its own Shamir recovery)
{
"name": "setup_to_delete_user_id",
"type": "DateTime"
},
{
"name": "share_recipients",
"type": "List<UserId>"
}
]
}
```

The certificate needs to include the previous certificate timestamp in the deletion certificate to link both certificates together.

### **Future evolution 2**: Specify a Shamir recovery setup template
Who need witch certificate ?

| certificate | author | share recipient |
|-------------|--------|-----------------|
| brief | x | x |
| share | | x |
| deletion | x | x |

### How to decide if a deletion certificate is valid ?

A setup can be identified by the tuple (author_user_id, timestamp) that we'll call shamir_id.
To decide is a deletion certificate is valid, the following questions must be asked

1. Is there a shamir setup with the corresponding shamir id ? No, means `shamir_setup_not_found`
2. Has this shamir id already a corresponding deletion certificate ? Yes, means `shamir_setup_already_deleted`
3. Is the share recipients list the same ? No, means `invalid_data`

## Bonus

### **Future evolution 1**: Specify a Shamir recovery setup template

Shamir recovery allows plenty of different configurations (single recipient, different
weight per recipient etc.), but we want to be able to set some limits here using the
Expand Down Expand Up @@ -803,3 +909,16 @@ On the other hand, approach 1) allow things like "recovery requires Alice, Bob a
requires Alice and Bob, or Adam alone". However given we cannot trust the server
on such precise configuration, a new certificate type must be introduced which is cumbersome :(
Also we should be able to provide approach 2) as part of approach 1).

### **Future evolution 2**: notify shamir author when shamir secret become irrecoverable

If Alice has setup a shamir with Bob, Mallory and John, each of then having one share and a threshold of two.
Then Bob and Mallory leave the organization. So this setup becomes unusable.

The goal would be to have a notification to prompt the user to setup a new shamir.
Depending on the configuration, if any of the share recipient is deleted a warning could be sent first
event if the shamir could still be used.

Two propositions could mitigate that:
- each time a user is deleted, if they were a share recipient a notification could be sent to users on the other end of this shamir setup.
- at each connection, check if share recipients are still valid.