Backup Key Shares

Introduction#

Key Splitting consists in splitting a secret key in several (currently, always two) key shares. One share alone is completely useless, but by combining two shares of a key one can recover the secret key.

A key share has another attribute than its value, it has an user_local_share_hash which is used for the guest frontend to identify which share it wants to retrieve. Technically speaking, the hash is the SHA-512 hash of the other share.

Creating a root key share#

Request#

POST https://api.misakey.com/root-key-shares

Cookies:

accesstoken (opaque token) (ACR >= 2): the identity must be linked to an account and this account must fit the one given in the body
tokentype: must be bearer

Headers:

X-CSRF-Token: a token to prevent from CSRF attacks.

JSON Body:

{
    "share": "o0hYlc2RurzJTiXldnnOMw",
    "user_local_share_hash": "axoGoSxJDiVWru3Sm-vdYQ"
}

account_id (string) (uuid): the account for which the shares has been created.
share (string) (base64): one of the shares.
user_local_share_hash (string) (unpadded url-safe base64): a hash of the other share.

Response#

Code:

HTTP 201 CREATED

JSON Body:

{
  "account_id": "b2dc8b7e-44e6-4510-b222-c914876fad1c",
  "share": "o0hYlc2RurzJTiXldnnOMw",
  "user_local_share_hash": "axoGoSxJDiVWru3Sm-vdYQ"
}

Getting a Root Key Share#

Request#

GET https://api.misakey.com/root-key-shares/:user-local-share-hash

Cookies:

accesstoken (opaque token) (ACR >= 2): the identity must be linked to an account and this account must fit the one for which the key has been created.
tokentype: must be bearer

Headers:

X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

user-local-share-hash (string): the hash of the key share.

Response#

Code:

HTTP 200 OK

JSON Body:

{
  "account_id": "b2dc8b7e-44e6-4510-b222-c914876fad1c",
  "share": "o0hYlc2RurzJTiXldnnOMw",
  "user_local_share_hash": "axoGoSxJDiVWru3Sm-vdYQ"
}

account_id (string) (uuid): the account for which the shares has been created.
share (string) (unpadded url-safe base64): one of the shares.
user_local_share_hash (string) (unpadded url-safe base64): a hash of the other share.