Export Key

POST /keys/{keyId}/export

• This endpoint is not enabled by default. Contact Dfns to have it activated.

• User action signature required. See User Action Signing for more information.

• Request headers required. See Request Headers for more information.

• Authentication required. See Authentication Headers for more information.

Dfns secures private keys by generating them as MPC key shares in our decentralized key management network. Our goal is to eliminate all single points of failure (SPOFs) associated with blockchain private keys.

In certain circumstances, however, customers require Dfns to export a private key. In this case, Dfns exposes the following endpoint which can be used in conjunction with our export SDK.

Dfns can not guarantee the security of exported keys as we have no way to control blockchain transactions once the single point of failure has been reconstituted. For this reason, this feature is restricted to customers who have signed a contractual addendum limiting our liability for exported keys. Additionally, by default exported keys can no longer be used to sign within the Dfns platform. Please contact your sales representative for more information.

Required Permissions

Name	Conditions
Keys:Export	Always Required

Key Export Flow

The private key which you need to export, will never be transmitted through Dfns system in one piece, or in clear (un-encrypted). The process follows this flow:

1. On your side (client-side), with the help of our export SDK library, you create an "export context" locally. This will generate an encryption/decryption key pair to perform the export in a secure way. This step corresponds to this line in our SDK key export example.

2. You then call the Key Export endpoint, providing the API with the previous encryption key for secure export. This step corresponds to this line in our SDK key export example.

3. On Dfns side, the export encryption key gets transmitted to each node of your Signing Cluster (Your Signing Cluster is the network of nodes, also referred as "signers", where your private key shares are securely stored). Each signer node will encrypt the corresponding key share to be exported. All encrypted key shares are then transmitted back to you.

4. On your side (client-side), with the help of our export SDK library, you will then decrypt each encrypted key share, and re-compose the key shares into a single private key. This step corresponds to this line in our SDK key export example.

Request Body

Property	Description	Type - Optional
encryptionKey	The public key of an asymmetric key pair used to encrypt the key shares prior to transmission.	String
supportedSchemes	An object with the format shown below.	Array<SupportedScheme>
delete	Whether the key should be deleted after export. Defaults to true when not specified.	Boolean (optional)

SupportedScheme

Property	Description	Type - Optional
protocol	CGGMP21, FROST, FROST_BITCOIN	String
curve	secp256k1, edd25519, stark	String

Example

{
    "encryptionKey": "AQNiFCgqtXFvRdNVciLzZ0hjZxumwtP0hfCrUDsymzWU5A==",
    "supportedSchemes": [
        {
            "protocol": "CGGMP21",
            "curve": "secp256k1"
        }
    ]
}

Response Body

Property	Description	Type - Optional
publicKey	Public key of the exported key.	String
protocol	CGGMP21, FROST, FROST_BITCOIN	String
curve	secp256k1, edd25519, stark	String
minSigners	Always 3. Mininum number of signers to complete a signature (TSS threshold).	Integer
encryptedKeyShares	An array of objects containing the encrypted keyshares. See format below.	Array<EncryptedKeyShare>

EncryptedKeyShare

Property	Description	Type - Optional
signerId	ID of the signer returned from List Signers.	String
encryptedKeyShare	The key share encrypted with the signer encryption key (public key, asymmetric encryption).	String

200 Success

{
  "publicKey": "0363fd944987c22382c2f34f8ffc53e1fc1e2def96baacd9cbaa5ff51bfb308e2b",
  "curve": "secp256k1",
  "protocol": "CGGMP21",
  "minSigners": 3,
  "encryptedKeyShares": [
    {
      "signerId": "9R4OQb12f8PrEQwFmwZ58ZsNHs6EcGQPWF3fSzhXbVk=",
      "encryptedKeyShare": "Op1j...4tQY"
    },
    {
      "signerId": "lGcHWQmdLtJ+4S+RIBFq704/Nox2bugUctVeLL0wPW8=",
      "encryptedKeyShare": "617Q...p7Yy"
    },
    {
      "signerId": "EX5PdJFcutVTJCgAcSGGGy264JwnrOLLyrZIqMHG67I=",
      "encryptedKeyShare": "YvUd...5t8y"
    },
    {
      "signerId": "ZokM6nUhGXHYhtQYE/NTeBEz5udvx13Ympcd1raQ4Fc=",
      "encryptedKeyShare": "W8pF...Nu7h"
    },
    {
      "signerId": "KaGnB8iWVpRKBRh+/sAJ0gz1cAZtjhHPufGRgkOXENo=",
      "encryptedKeyShare": "7ZZM...Xgm3"
    }
  ]
}