Key Lifecycle

Once we have already generated our key shares, we can refresh and also export them.
We show how to do this below.

Key Refresh

Key Refresh (sometimes referred to as "Key Rotation") is a protocol that allows the devices to compute entirely new secret shares of the same public key.
Refreshing the key material frequently is considered a best practice for enhanced security, as it adds an element of time to the security setting.
Since even if one secret share was compromised, then after Key Refresh the compromised secret share will no longer be useful. Below is an example of how to use Key Refresh:

ECDSA Node

import { Ecdsa } from '@sodot/sodot-node-sdk';

const N = 3;
const T = 2;
const ecdsa = new Ecdsa();
const API_KEY = 'MY_API_KEY';
// An EcdsaKeygenResult was previously generated using keygen
const keygenResult = await ecdsa.keygen(...);
// Some time passes ...

// We now refresh the secret key material of our public key
// Your server creates a room for 3 parties
const refreshRoomUuid = await ecdsa.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
const refreshedKeygenResult = await ecdsa.refresh(refreshRoomUuid, keygenResult)
// Note: refreshedKeygenResult.pubkey == keygenResult.pubkey
// refreshedKeygenResult can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

Ed25519 Node

import { Ed25519 } from '@sodot/sodot-node-sdk';

const N = 3;
const T = 2;
const ed25519 = new Ed25519();
const API_KEY = 'MY_API_KEY';
// An Ed25519KeygenResult was previously generated using keygen
const keygenResult = await ed25519.keygen(...);
// Some time passes ...

// We now refresh the secret key material of our public key
// Your server creates a room for 3 parties
const refreshRoomUuid = await ed25519.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
const refreshedKeygenResult = await ed25519.refresh(refreshRoomUuid, keygenResult)
// Note: refreshedKeygenResult.pubkey == keygenResult.pubkey
// refreshedKeygenResult can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

ECDSA Web

import { Ecdsa } from '@sodot/sodot-web-sdk';

const N = 3;
const T = 2;
const ecdsa = new Ecdsa();
const API_KEY = 'MY_API_KEY';
// An EcdsaKeygenResult was previously generated using keygen
const keygenResult = await ecdsa.keygen(...);
// Some time passes ...

// We now refresh the secret key material of our public key
// Your server creates a room for 5 parties
const refreshRoomUuid = await ecdsa.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
const refreshedKeygenResult = await ecdsa.refresh(refreshRoomUuid, keygenResult)
// Note: refreshedKeygenResult.pubkey == keygenResult.pubkey
// refreshedKeygenResult can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

Ed25519 Web

import { Ed25519 } from '@sodot/sodot-web-sdk';

const N = 3;
const T = 2;
const ed25519 = new Ed25519();
const API_KEY = 'MY_API_KEY';
// An Ed25519KeygenResult was previously generated using keygen
const keygenResult = await ed25519.keygen(...);
// Some time passes ...

// We now refresh the secret key material of our public key
// Your server creates a room for 3 parties
const refreshRoomUuid = await ed25519.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
const refreshedKeygenResult = await ed25519.refresh(refreshRoomUuid, keygenResult)
// Note: refreshedKeygenResult.pubkey == keygenResult.pubkey
// refreshedKeygenResult can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

ECDSA RN

import { StatefulEcdsa } from '@sodot/sodot-react-native-sdk';

const N = 3;
const T = 2;
const ecdsa = new StatefulEcdsa();
const API_KEY = 'MY_API_KEY';
// Refreshing the secret key material
// Your server creates a room for 3 parties
const refreshRoomUuid = await ecdsa.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
await ecdsa.refresh(refreshRoomUuid, 'myKeyName', 'myNewKeyName');
// 'myNewKeyName' can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

Ed25519 RN

import { StatefulEd25519 } from '@sodot/sodot-react-native-sdk';

const N = 3;
const T = 2;
// We now refresh the secret key material of our public key
// Your server creates a room for 3 parties
const refreshRoomUuid = await ed25519.createRoom(N, API_KEY);
// All parties now join the refresh room using their current secret key material
await ed25519.refresh(refreshRoomUuid, 'myKeyName', 'myNewKeyName');
// 'myNewKeyName' can now be used for signing under the same T threshold, as well as be refreshed again

API reference

Full details can be found here.

ECDSA Go

import "github.com/sodot-rs/sodot-go-sdk"

const N = 3
const T = 2
const API_KEY = "MY_API_KEY"
// An EcdsaSecretShare is generated using Keygen
// secretShare, pk, err := ecdsa.Keygen(...)
secretShare := sodot.EcdsaSecretShare{}
// Some time passes ...
// We now refresh the secret key material of our public key
ecdsa := sodot.NewEcdsa("")
refreshRoomUuid, err := ecdsa.CreateRoom(N, API_KEY)
if err != nil {
    panic(err)
}

// Note: the public key returned here is the same as the one returned by the keygen
refreshedShare, _, err := ecdsa.Refresh(refreshRoomUuid, secretShare)
if err != nil {
    panic(err)
}
// refreshedShare can now be used for signing under the same T threshold, as well as be refreshed again
_ = refreshedShare

API reference

Full details can be found here.

Ed25519 Go

import "github.com/sodot-rs/sodot-go-sdk"

const N = 3
const T = 2
const API_KEY = "MY_API_KEY"
// An Ed25519SecretShare is generated using Keygen
// secretShare, pk, err := ed25519.Keygen(...)
secretShare := sodot.Ed25519SecretShare{}
// Some time passes ...
// We now refresh the secret key material of our public key
ed25519 := sodot.NewEd25519("")
refreshRoomUuid, err := ed25519.CreateRoom(N, API_KEY)
if err != nil {
    panic(err)
}

// Note: the public key returned here is the same as the one returned by the keygen
refreshedShare, _, err := ed25519.Refresh(refreshRoomUuid, secretShare)
if err != nil {
    panic(err)
}
// refreshedShare can now be used for signing under the same T threshold, as well as be refreshed again
_ = refreshedShare

API reference

Full details can be found here.

Key Export

In the case that we want to stop using the MPC SDK for a specific set of keys, it is possible to export the full private key out of the system to be used elsewhere.
Note that by running Key Export we break the security model defined by splitting the private key into key shares. This operation is supported strictly in order to prevent vendor-lock and provide an exit strategy from using the SDK.
Keys that have undergone Key Export should never again be used as key shares in the context of the SDK.
Note that by design only one device will receive the full private key, this enables key export in cases where it only makes sense for one device to view the private key (such as a client-server model).
Below is an example of how to use Key Export:

ECDSA Node

import { Ecdsa } from '@sodot/sodot-node-sdk';

const N = 3;
const T = 2;
const ecdsa = new Ecdsa();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ecdsa.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ecdsa.exportID(keygenResult);
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ecdsa.exportFullPrivateKey(exportRoomUuid, keygenResult, exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be a normal base58 string xpriv - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ecdsa.derivePrivateKeyFromXpriv(keyExportResult, derivationPath);
const derivedPubkey = await ecdsa.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based ECDSA signing software

API reference

Full details can be found here.

Ed25519 Node

import { Ed25519 } from '@sodot/sodot-node-sdk';

const N = 3;
const T = 2;
const ed25519 = new Ed25519();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ed25519.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ed25519.exportID(keygenResult);
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ed25519.exportFullPrivateKey(exportRoomUuid, keygenResult, exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be an extended private key in a custom format (spriv) - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ed25519.derivePrivateKeyFromSpriv(keyExportResult, derivationPath);
const derivedPubkey = await ed25519.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based Ed25519 signing software

API reference

Full details can be found here.

ECDSA Web

import { Ecdsa } from '@sodot/sodot-web-sdk';

const N = 3;
const T = 2;
const ecdsa = new Ecdsa();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ecdsa.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ecdsa.exportID(keygenResult);
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ecdsa.exportFullPrivateKey(exportRoomUuid, keygenResult, exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be a normal base58 string xpriv - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ecdsa.derivePrivateKeyFromXpriv(keyExportResult, derivationPath);
const derivedPubkey = await ecdsa.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based ECDSA signing software

API reference

Full details can be found here.

Ed25519 Web

import { Ed25519 } from '@sodot/sodot-web-sdk';

const N = 3;
const T = 2;
const ed25519 = new Ed25519();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ed25519.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ed25519.exportID(keygenResult);
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ed25519.exportFullPrivateKey(exportRoomUuid, keygenResult, exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be an extended private key in a custom format (spriv) - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ed25519.derivePrivateKeyFromSpriv(keyExportResult, derivationPath);
const derivedPubkey = await ed25519.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based Ed25519 signing software

API reference

Full details can be found here.

ECDSA RN

import { StatefulEcdsa } from '@sodot/sodot-react-native-sdk';

const N = 3;
const T = 2;
const ecdsa = new StatefulEcdsa();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ecdsa.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ecdsa.exportID('myKeyName');
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ecdsa.exportFullPrivateKey(exportRoomUuid, 'myKeyName', exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be a normal base58 string xpriv - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ecdsa.derivePrivateKeyFromXpriv(keyExportResult, derivationPath);
const derivedPubkey = await ecdsa.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based ECDSA signing software

API reference

Full details can be found here.

Ed25519 RN

import { StatefulEd25519 } from '@sodot/sodot-react-native-sdk';

const N = 3;
const T = 2;
const ed25519 = new StatefulEd25519();
const API_KEY = 'MY_API_KEY';
// Exporting the secret key material
// Your server creates a room for 2 parties
const exportRoomUuid = await ed25519.createRoom(T, API_KEY);

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
const exportTo = await ed25519.exportID('myKeyName');
// It will the propagate this exportID to the other parties
// Threshold (t) parties will now need to join the export room
const keyExportResult = await ed25519.exportFullPrivateKey(exportRoomUuid, 'myKeyName', exportTo);
// keyExportResult is 'undefined' except for the party with exportTo as its exportID
// For the exporting party it will be a normal base58 string xpriv - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
const derivationPath = new Uint32Array([44, 60, 0, 0, 0]);
const derivedPrivateKey = await ed25519.derivePrivateKeyFromSpriv(keyExportResult, derivationPath);
const derivedPubkey = await ed25519.derivePubkey(keygenResult, derivationPath);
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based ECDSA signing software

API reference

Full details can be found here.

ECDSA Go

import "github.com/sodot-rs/sodot-go-sdk"

const N = 3
const T = 2
const API_KEY = "MY_API_KEY"
ecdsa := sodot.NewEcdsa("")
exportRoomUuid, err := ecdsa.CreateRoom(N, API_KEY)
if err != nil {
    panic(err)
}

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
exportTo = sodot.exportID(secretShare);
// It will the propagate this KeygenID to the other parties
// Threshold (t) parties will now need to join the export room
privkey, err := ecdsa.ExportFullPrivateKey(exportRoomUuid, secretShare, exportTo);
if err != nil {
    panic(err)
}

// privkey is "" except for the party with exportTo as its KeygenID
// For the exporting party it will be a normal base58 string xpriv - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
derivationPath := []uint32{44, 60, 0, 0, 0}
derivedPrivateKey, err := ecdsa.DerivePrivateKeyFromXpriv(privkey, derivationPath);
if err != nil {
    panic(err)
}
derivedPubKey, err := ecdsa.DerivePubkey(secretShare, derivationPath)
if err != nil {
    panic(err)
}
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based ECDSA signing software

API reference

Full details can be found here.

Ed25519 Go

import "github.com/sodot-rs/sodot-go-sdk"

const N = 3
const T = 2
const API_KEY = "MY_API_KEY"
ed25519 := sodot.NewEd25519("")
exportRoomUuid, err := ed25519.CreateRoom(N, API_KEY)
if err != nil {
    panic(err)
}

// Only one of the parties will receive the full private key, this party will retrieve its exportID:
exportTo = sodot.exportID(secretShare);
// It will the propagate this KeygenID to the other parties
// Threshold (t) parties will now need to join the export room
privkey, err := ed25519.ExportFullPrivateKey(exportRoomUuid, secretShare, exportTo);
if err != nil {
    panic(err)
}

// privkey is "" except for the party with exportTo as its KeygenID
// For the exporting party it will be an extended private key in a custom format (spriv) - more details in the link below
// It is most likely that importing the key elsewhere will only be supported for specific derivation paths
// Hence, it is possible to get the derived private key as well as public key for any derivation path
derivationPath := []uint32{44, 60, 0, 0, 0}
derivedPrivateKey, err := ed25519.DerivePrivateKeyFromSpriv(privkey, derivationPath);
if err != nil {
    panic(err)
}
derivedPubKey, err := ed25519.DerivePubkey(secretShare, derivationPath)
if err != nil {
    panic(err)
}
// derivedPrivateKey is the private key for derivedPubkey and can now be imported into any non-MPC based Ed25519 signing software

API reference

Full details can be found here.