Skip to main content

Crypto Provisions

Crypto provisions are a mechanism that let you create auto-invitations for users that still don't a Misakey account, or which Misakey account is not yet ready to receive standard auto invitations.

Crypto provisions can only be created by organizations for the moment.

Auto-invitations must be encrypted with the public key of their recipient. For most existing Misakey accounts, you can send them auto invitations by using their identity public key. But it can happen that some Misakey accounts don't have an identity public key. Also, you may want to create auto-invitations for people who don't have a Misakey account yet.

Creating a crypto provision let you do this by generating a key pair yourself and using the public part as a substitute to the missing identity public key.

Since you will still have to send an invitation link to the person you created a crypto provision for (to give her the secret part of the key pair you generated), you may wonder what is the advantage of crypto provisions over simply sending classic invitation links. The answer is that if you create several boxes for a same user, instead of sending N invitation links to this user, you can create a crypto provision and send one auto-invitation to this provision for each of the boxes. As a result you only have one invitation link to send (the one corresponding to the provision) to the person to give her access to all the boxes you created for her.

Creating a Crypto Provision#

First, generate an encryption key pair (see encryption documentation). Split the secret key into two key shares (see key shares documentation about the creation of key shares).

The JSON object for the creation of a crypto provision contains the public key, the misakey share of the secret key, as well as the hash of the user share of the secret key :

{
"public_key": "eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g",
"misakey_key_share": "9ALK2WOpvEmOJx7WUWVOg-68IIc8lJl8I8CxMeLg4EuGiaz8JwRDVgAT7LV7ATHManMcS3NRhlNXy5T3FVvu_Q",
"user_key_share_hash": "fDy_i2AGOQFKj_kJ061Up_ob1YyHIUl-0lhiFMAkjWYLnOzhN3t5R9H1MWhBQw4zVKLzaXblVvGnvsH_Mmxx8Q"
}

There is no dedicated endpoint at the moment for the creation of crypto provisions. Instead, provisions are created by passing extra data during a call to POST /organizations/:oid/boxes.

{
(... rest of the box creation payload)
"crypto": {
"provisions": {
"michel@misakey.com": {
"public_key": "eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g",
"misakey_key_share": "9ALK2WOpvEmOJx7WUWVOg-68IIc8lJl8I8CxMeLg4EuGiaz8JwRDVgAT7LV7ATHManMcS3NRhlNXy5T3FVvu_Q",
"user_key_share_hash": "fDy_i2AGOQFKj_kJ061Up_ob1YyHIUl-0lhiFMAkjWYLnOzhN3t5R9H1MWhBQw4zVKLzaXblVvGnvsH_Mmxx8Q"
}
}
}
}

Note that the provision creation object is associated to an key (here, "michel@misakey.com"). The provision will be linked to this email and to your organization, and only you and user "michel@misakey.com" will see the existence of this provision.

The provision can be used to send auto-invitations in the same call that creates it (see auto-invitation documentation about how to create them):

"crypto": {
"invitation_data": {
"eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g": "fbs05eripjc7PkZsmeBPFRxwpfj_0ARt6QjaO3B2PpIvLxaTVDvSfW6_V97HUxA7qDN5vTdi5xWq"
},
"provisions": {
"michel@misakey.com": {
"public_key": "eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g",
"misakey_key_share": "9ALK2WOpvEmOJx7WUWVOg-68IIc8lJl8I8CxMeLg4EuGiaz8JwRDVgAT7LV7ATHManMcS3NRhlNXy5T3FVvu_Q",
"user_key_share_hash": "fDy_i2AGOQFKj_kJ061Up_ob1YyHIUl-0lhiFMAkjWYLnOzhN3t5R9H1MWhBQw4zVKLzaXblVvGnvsH_Mmxx8Q"
}
}
}

Note that the provision secret key is not sent to Misakey. Neither is the user key share. Use the user key share to create an invitation link corresponding to this crypto provision: TODO invitation link format.