StatefulExportableEd25519
@sodot/sodot-react-native-sdk • Docs
@sodot/sodot-react-native-sdk / StatefulExportableEd25519
Class: StatefulExportableEd25519
Class providing the functionality for the Exportable Ed25519 protocol via the FROST MPC protocol. This class provides a Stateful API meaning that key material will be stored by the SDK on the device.
Example
// Your server side creates a room for 3 parties using its API_KEY
// Creating a room uuid should always happen on the server side using your API_KEY
const N = 3;
const T = 2;
const exportableEd25519 = new StatefulExportableEd25519();
const API_KEY = 'MY_API_KEY';
const keygenRoomUuid = await exportableEd25519.createRoom(N, API_KEY);
// All parties call initKeygen to get a keygenId
const keygenId = await exportableEd25519.initKeygen('myKeyName');
// All parties receive the keygenIds from all other parties
const keygenIds = [keygenId1, keygenId2];
// One party joins the keygen room using acting as the sampler:
const publicKey = await exportableEd25519.sampleKey(keygenRoomUuid, N, T, 'myKeyName', keygenIds);
// The remaining parties join the key sampling ceremony using:
const publicKey = await exportableEd25519.receiveKey(keygenRoomUuid, N, T, 'myKeyName', keygenIds);
Constructors
new StatefulExportableEd25519()
new StatefulExportableEd25519(
hostUrl?):StatefulExportableEd25519
Constructs a new StatefulExportableEd25519 instance.
Parameters
• hostUrl?: string
Returns
Methods
createRoom()
createRoom(
numParties,apiKey):Promise<string>
Creates a room for the given number of parties. A room is a one time instance used to perform a single MPC operation(keygen/signing/refresh etc.) between parties
This function should be called in the backend so to not embed the API key in code that is distributed to the users. After the backend calls this function, the other parties can join the room by calling the relevant keygen/signing/refresh/etc. operation.
Parameters
• numParties: number
The number of parties that will join the room. (an integer in range 1..65_535)
• apiKey: string
An API key is required to create a room
Returns
Promise<string>
The UUID of the created room.
deletePrivateKeyShareFromDevice()
deletePrivateKeyShareFromDevice(
keyName):Promise<void>
Delete the private key share associated with the given keyName.
WARNING: This completely deletes the secret share from the device.
Deletion is irreversible.
Parameters
• keyName: string
The name of the keypair to delete.
Returns
Promise<void>
exportFullPrivateKey()
exportFullPrivateKey(
roomUuid,keyName,toExportID):Promise<undefined|string>
Combine all secret shares and export the full private key to a single party. Requires a threshold amount of parties to participate.
Parameters
• roomUuid: string
The UUID of the export room.
• keyName: string
The name of the keypair.
• toExportID: string
The exportID from the party that will receive the private key.
Returns
Promise<undefined | string>
The party being exported to will receive a hex-encoded private key (RFC8032 format), while the rest receive undefined.
exportID()
exportID(
keyName):Promise<string>
The party that expects to receive the private key needs to call this function before exportFullPrivatekey.
It must then transmit the ID to threshold-1 parties, this can be done in an untrusted channel (as if the parties use different keys this will break)
Once the parties have the exportID of the party they want to export the private key to, the party and the threshold-1 participants need to call exportFullPrivatekey with that ID.
Parameters
• keyName: string
The name of the keypair that will be generated later. This name will be used to retrieve a private key associated with the keygenId that is necessary for the keygen operation.
Returns
Promise<string>
A string that contains a base58 string exportID.
getAllStoredKeyNames()
getAllStoredKeyNames():
Promise<string[]>
Returns
Promise<string[]>
A list of all the key names stored on the device.
getPubkey()
getPubkey(
keyName):Promise<string>
Retrieves the public key associated with the given keyName.
Parameters
• keyName: string
The name of the keypair.
Returns
Promise<string>
The public key as a hex string.
importPrivateKeyShareData()
importPrivateKeyShareData(
keyName,secretShareHex):Promise<void>
Import a private key share from a backup.
Parameters
• keyName: string
The name to store the key under.
• secretShareHex: string
The hex-encoded secret share.
Returns
Promise<void>
initKeygen()
initKeygen(
keyName):Promise<string>
All parties must call this function before calling keygen. The keyName for the key that will be generated during keygen (and later used for signing as well) is set here. All parties receive a keygenId as an output from this function. This keygenId must be sent through an authenticated communication channel to all other devices we wish to perform keygen with. Once we have the keygenId-s of all parties, then keygen can be called with the same keyName as was given here.
Parameters
• keyName: string
The name of the keypair that will be generated later. This name will be used to retrieve a private key associated with the keygenId that is necessary for the keygen operation.
Returns
Promise<string>
A base58 string that represents a keygenId.
receiveKey()
receiveKey(
roomUuid,numParties,threshold,keyName,keygenIds):Promise<Uint8Array<ArrayBufferLike>>
Generate a keypair where the party receives a key from a sampler. This function will return the public key of the keypair. The private key is stored in the secure storage of the device and will be used to sign messages.
Parameters
• roomUuid: string
The UUID of the keygen room.
• numParties: number
The number of parties that will join the keygen room. (an integer in range 1..65_535)
• threshold: number
The threshold of the keypair that will be generated. (an integer in range 1..65_535)
• keyName: string
The name of the keypair. This must be the same name used in initKeygen and will later be used to retrieve the private key share from the secure storage when signing a message.
• keygenIds: string[]
The keygenId outputs from initKeygen of all other parties we wish to perform keygen with, these must have been received through an authenticated communication channel.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The public key of the generated keypair.
refresh()
refresh(
roomUuid,keyName,newKeyName):Promise<void>
Used for refreshing the secret material of all parties without altering the public key at all.
Takes a keyName and newKeyName as input and stores the fresh key material under newKeyName.
Be careful to delete the old keyName share before it is certain that all devices have properly stored
the fresh secret material under newKeyName.
Note that the new secret materials may only be used with each other, attempting to use older secret materials
with newer ones for signing will result in failure.
The motivation for using refresh is to enhance security by switching the secret key material frequently, this means that an adversary will
need to compromise multiple devices at the same time in order to compromise the private key.
Parameters
• roomUuid: string
The UUID of the refresh room.
• keyName: string
The name of the key that will be refreshed.
• newKeyName: string
The new name of the key used to store the fresh secret material.
Returns
Promise<void>
reshareNewParty()
reshareNewParty(
roomUuid,oldThreshold,newThreshold,keyName,keygenIds):Promise<Uint8Array<ArrayBufferLike>>
WARNING: Key resharing is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it, as incorrect usage might lead to the detriment of the private key security.
Resharing the private key of the t-of-n quorum of signers, the resultant key shares will be of the exact same public key as the previous quorum.
This is the method that a new party should use for receiving a key share in the new quorum.
Parameters
• roomUuid: string
The UUID of the reshare room.
• oldThreshold: number
The threshold of the existing quorum.
• newThreshold: number
The threshold of the keypair of the new quorum.
• keyName: string
The name of the keypair to store.
• keygenIds: string[]
The keygenId outputs from initKeygen/exportID of all parties.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The public key for the new quorum, same as the old pubkey.
reshareRemainingParty()
reshareRemainingParty(
roomUuid,newThreshold,oldKeyName,newKeyName,keygenIds):Promise<Uint8Array<ArrayBufferLike>>
WARNING: Key resharing is an advanced feature of the SDK. We strongly advise consulting with the Sodot team before using it.
Resharing the private key of the t-of-n quorum of signers for a party that already has a key share.
Parameters
• roomUuid: string
The UUID of the reshare room.
• newThreshold: number
The threshold of the keypair of the new quorum.
• oldKeyName: string
The name of the existing keypair.
• newKeyName: string
The name of the new keypair.
• keygenIds: string[]
The keygenId outputs from all parties.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The public key for the new quorum, same as the old pubkey.
retrievePrivateKeyShareForBackup()
retrievePrivateKeyShareForBackup(
keyName):Promise<string>
Retrieve the private key share associated with the given keyName. The returned value is a hex string that encodes the key material. Notice: This value must be kept secret!
Parameters
• keyName: string
The name of the keypair.
Returns
Promise<string>
The private key share of the keypair.
sampleKey()
sampleKey(
roomUuid,numParties,threshold,keyName,keygenIds):Promise<Uint8Array<ArrayBufferLike>>
Generate a keypair where one party acts as a sampler. This function will return the public key of the keypair. The private key is stored in the secure storage of the device and will be used to sign messages.
Parameters
• roomUuid: string
The UUID of the keygen room.
• numParties: number
The number of parties that will join the keygen room. (an integer in range 1..65_535)
• threshold: number
The threshold of the keypair that will be generated. (an integer in range 1..65_535)
• keyName: string
The name of the keypair. This must be the same name used in initKeygen and will later be used to retrieve the private key share from the secure storage when signing a message.
• keygenIds: string[]
The keygenId outputs from initKeygen of all other parties we wish to perform keygen with, these must have been received through an authenticated communication channel.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The public key of the generated keypair.
sign()
sign(
roomUuid,keyName,msg):Promise<Uint8Array<ArrayBufferLike>>
Sign a message with the secret share associated with the given keyName. The secret share is stored in the secure storage of the device. Notice that unlike ECDSA, in Ed25519 there's no need to hash the message before signing it.
Parameters
• roomUuid: string
The UUID of the signing room.
• keyName: string
The name of the keypair, this name was used when generating the keypair.
• msg: string | Uint8Array<ArrayBufferLike>
The message to be signed. Either as a Uint8Array or as a hex string.
Returns
Promise<Uint8Array<ArrayBufferLike>>
The signature of the message, this signature can be verified using the public key of the keypair.