Decrypt End User Full Private Key

Recover private keys for end-user wallets.

Customers who choose to hold the backup encryption key are able to completely recover the private keys for the end users wallets using the recover-end-user-key command. Use this command in case of disaster recovery in the highly unlikely event that Fordefi loses all of the shares saved on our servers.

Before you start

To import keys successfully, you need:

  • An API User access token: Learn how to generate the token here.

  • The platform share decryption key: Depending on the type of disaster-recovery backup you have previously created, this is either:

    • Two recovery phrases, held by two admins of your workspace, or
    • An RSA private key that corresponds to the public key you uploaded to the platform when setting up your backup.
  • The end-user share decryption key: the symmetric encryption key that your application passed to the backupKeys function when backing up that particular end user's device share.

  • Fordefi recovery tool: Download it from the Fordefi documentation site.

Procedure

  1. Call the Get End User API, passing the end user's ID as input. The response contains the encrypted shares for each of the key types: ECDSA, EDDSA, STARK, and Schnorr, as follows:

    {
     "id": "dea3eca6-96b6-4776-87af-b5ae2a3205df",
     // ... additional fields
     "ecdsa": {
         "id": "16c67bf4-7665-4c22-b337-631e2f23e567",
         "xpub": "xpub661MyMwAqRbcEj6CZiPcVHxrC1uVihJbVpioLafRT1aqvpagnEtoUjKmd5wzdL9Behf3Fj26RBjWpscs1gzrWU2GuWCx69UUJsbNKX8T3Cd",
         "encrypted_shares": {
             "device": "eyJjaXBoZXJ0ZXh0IjoiUnNadjM2Z1N1dnpWQ29pbHBmV0s3T2pZYkJ1WTVhRWJlWkdzQnY4bHUzUTRYcEpSR3hYMnJGMFJVSmc0dllzMHorejlVQzd6UTkrTEU4eTVHZTYrYUtCWWhxZkt4K2RPdmsxRm9ubUpndG1wMmF2eElIQkdiSjhEdjgwSVR4cnBOaStld1lqYWtTaUIrbCszbWM5NGVMN1VYaDBZTkxVeC9McG44VzlyZHRQMFhMSFR5WkVPYitUU052aGhrZkRYbnh2TWVxT0NEbCt2RkFQeEI4NnZxOHFway9IbFZyR3hSSzY5Z2lpY002MXZtbTg9Iiwibm9uY2UiOiIwY21lRlhYeXJtNTRZUU5yIn0=",
             "platform": [
                 "eyJlbmNyeXB0ZWRfc2Vzc2lvbl9rZXkiOiJLNTZVZFd0Mmx4VG5GclIwcSt0U3c5VmtLWDg3bzV1RGF0Q1VnSWVkencwME9UWDlqbXAwU1ozNVJ4SHN1OFFIYUk0MVdJUzJqNXVUU3ZlcndqMTFPQTZ6RGZPMXVOendIYkFqQkVoNmFKZnNUTkx1S3AvZkY5SjlEWlQvdk1QUE8ySk1Nd2pIWjJlVGtrWE1ZNEVLcU9WWHJTQnhXTk9aaEg4TTBtaVRTM1NtcjJ0a2pFWldjTndwUlNvUGN5MFM0OGFnd290ZlErRXIwVS8zK3lLLzlQQ1JRcUNrSmt1S0ZuRXlBRXFiK0dXOHkwdGNNU1NITy9qeVVxWUlQNHdsbTh4MktKdGdMOGRwbE5UQTM5YVQvdCthWitvNGRBY1dvdUYvTXQ0TjM1a1dSUnVQZEE4OUxpWStKbGUxVTJqeHg0bHBJWi9mendFK25Nc3ZJaVZ0ZEE9PSIsIm5vbmNlIjoiSmh6M0NjS3crQS9DdGpSSSIsImNpcGhlcnRleHQiOiJCcmRKaTZ2VTN4cFh3M1Y0T1NnSzRERzNoUGdhd2IySnVXcExZa2lqUkVhbDU4ZEo0NHc5QzRWbUtpSW5LWlNxIn0="
             ]
         },
         "chain_code": "EnQ4jvOPWr1MWZRzTncJo2pVky2CBAbyh4kRPM8HAqw="
     },
     "eddsa": {
         // ... 
     }
    }

    For each key type you would like to recover, make a note of the following fields:

    • the device share (encrypted_shares->device)
    • the platform share (encrypted_shares->platform)
    • the chain code: an additional data element used to derive wallet addreses
  2. Call the List Vaults API endpoint to get the vault metadata. The response contains the following data:

    {
     "total": 1,
     "page": 1,
     "size": 50,
     "vaults": [
         {
             "id": "1f2ad7d1-e940-4d45-999d-7c54c3a39553",
             "name": "Demo User 3's Vault",
             "derivation_path": "m/44/60/0/0/0",
             // ...
         },
         // ...
     }

    Make a note of the derivation paths of the vaults you want to recover.

  3. For each vault you wish to recover, run the recovery tool: recovery-tool recover-end-user-key [flags], where the required flags are:

    • The metadata of the vault to be recovered:
      • --key-type: The key type to recover: ecdsa-secp256k1 | eddsa-ed25519 | ecdsa-stark | schnorr-secp256k1.
      • --key-derivation-path: The derivation path of the vault, as returned by the List Vaults API.
      • --chain-code: The chain code of the key in base64 format, as returned from the Get End User API.
    • The platform share recovery information:
      • --platform-backup-type: Platform's backup type: public-key | key-share.
      • --platform-encrypted-share: Platform encrypted key shares in base64 format as returned from the Get End User API. Whether it contains one or two shares depends on the backup type.
    • The end-user share recovery information:
      • --device-backup-type: [Optional] Device's backup key type. Only symmetric is currently supported.
      • --device-backup-key: The key to be used to decrypt encrypted device share.
      • --device-encrypted-share: Device's encrypted share in base64 format as returned from the Get End User API.
    • --output: [Optional] File path to output the recovered private key. Stdout if not specified.
  4. The recovery tool will then output the private key of the vault:

    {
      "private_key_hex": "01a64f1c14c017ed01b8e6e2048e5da0b96e639fe1d2f12cdb8b093a32d88290",
      "extended_private_key": "xprvA36uJQmWgPwSnxmh1D3dZPtVdWuLrwFC9PCGVonnvsTu4Z15jPByBfu63FFpBgWUZ5tbFsVKpzosGgabwQGrEhmbK3RUoVYsSdvACXkCK2p",
      "public_key_hex": "d0aea94569601e30e8ac951e83fe745ea9d5ba9474a1c316ea36a28a4b7f3aa8",
      "extended_public_key": "xpub6G6FhvJQWmVk1SrA7EadvXqEBYjqGPy3Wc7sJCCQVCzswMLEGvWDjUDZtTyGeMDKzizCURWfDoyF5eeCG4A62RvNUJZV1pPR3dq31HvPXh8"
    }

    For ECDSA-based chains, you can use then load the private key into an external wallet. For EDDSA-based chain, you will need to use the recovery tool to sign transactions using the recovered key, as explained in the recovery guide.

Examples

This example demonstrates the recovery command when the platform share is backed up using recovery phrases:

./recovery-tool recover-end-user-key \
  --key-type ecdsa-secp256k1 \
  --key-derivation-path m/44/60/1/0/0 \
  --device-backup-type symmetric \
  --device-encrypted-share eyJjaXBoZXJ0ZXh0IjoiY0RZeU04em9rdkhZOUovb1RlaUZYMmRvdlhXTVR1QzlzTTZTYkNNS3A3RTE5OVB2a3lIWVU2UmVVNndVOHlnYmlDWFpldFNNMitSTXVFZFh3ai9WMGpkNlFvM1YwUlZBVnZFR0kzYjhnMUhUcDJrdjZ5OTVvcTV6bDBxL2NGSWtBcEVOZkp6Z3dVL1pCYWtoTVFWQVRZcm5iZmk2bkVwMjJuUmJyVnJaQnpydEJqbEtZRk00UzFqQUtpWFh1WDdiK1ZXRGJtVDhQT2RacUxmdWR3TGNYZlRqVndsd0dZUENVSzBESzI2R3BxejhiMnVzUjVYY3VjS2tZaU1sSUJ4TUtHbjJYb2FRRkJoQXhCTXptOG9ydFZqVzBDTXlPcWxyWUVPcjJoa2E3VGEvY3JYcDVVZzEzeWNackdVVjRheHl3Q2lDRlBjSjFpY1E5elJwVERteG8yYS9hNkhEZkFyeXNWOUt4bUpBci9UTnZycmtSc0dxMzViSXN2UXJnREhnZ0NnK2RPSk1mZW1saHovSFV0S1pWU3pOTVFlN0R3VlRDR0poQUExNmFaamk2d1hDaGpDeVdBNnpRU1ArRzEzMmZiRXVyL2lKNzNjNERadVhuaXk1S1hxczNhVFRiRE5jNHl0QWh5LzJ2OStKejBqN2x5UWt2T2tCcVM2elJHYW4zb2thSzRnbTY3WUJ1TlZHSGY4YmlFQkNQeHdkVnJISVFYVWVWblptc3Q5RDA0QW4zc0ZZRnA0TDhmbFp2SlliTnFnbnF6eUc0UzlSajNhcFMvM3I0MnJjV2hPQlFVZmVScmlFWlVWUjFPc0J6TEtsU2g3ZnE0M0k1L2hsYUxoYUhNSDBmdnlmaUY5L1htbFV0cld6bGFVelh6amJhTW1MSjc5NU1KUXZZcG9CdzlGeEhNYko2TjZyWk11R0Zvb2dSZ1FBcEUyc0V6VzcwajFjaDg5aHh4YjVFa3l2MlRBVG1NMmdxQ1kvbkpZNm9NZEpiandPeDhyQ2E4cVo2VHdXdlQ3bmdvUFJETWZZaUNvMUIyQ0VteVAwN0V4VjNFeVp0SEFxYjBYZkhCdklBNmtzZnBqamZ5d2ptZ3VLNkljNEJrTjRETXlVWmNzd0w2MkVYS2ZMSVFhKy95d1JaMk50WCtXQ21HY2JKeXFCSjUyNlFrOEJ1UXhXMWlKREhvZVdXb2dQVTlWYjlqZWNSWnBQNG5JamF4Y291aDh0bzdYalp0bSswMHR0c3VnS0RqYVlkZjlUWEZLVzQ3bzF2M2EvUGNJMHhKS25icFlBZDVGalpNdDFCQXEwUHFhM0JQd1VPYnhPc1NVT0Yrb0d1V1YzakdwNmQ0K0IwQ3pSUGxWRE1hVzY2c0FyanllL0hGZzB1TTBHUHRMQU1uN0RnOTNrQWQ0WngveDJxU1N5ZklJa0NuSE93THRoL0lPeFdGb3hsdzdEdFBpWVJkbnZjK2haNzdJcVEyb2M4TkJTZGhkZ2taVzVNWTc0c2EzVEI2d3ZVelJybkVEYTNicTB3eG9WcHU2N3Q0TkpZR0ROMk9LcGVKOHhhWDRwYi9FcFJVRVdMNStWQXA1NXhzblJFUEs2UGVZV2Q0bE1GWGtWUkVDQ2RkaWkvMXlRV21Cdzg2aEk3aG03UEt2NW01MGJWTzh4akZLWDI2MGw1dlo1YmdTbEFhbkdRbk9hOHd4U1ljMVMrcHJzb1V1RFFjN0c5QjJsWW5rR0NzSmo1SmhTVURaY3ZrVmdDaTlDMk9HSHo2V2w4WUdWd3NXMStEMmV5RjhqVWRCTHBKRmZvTEd1a0Q2MCs5WS9kVENiZHh5b0RLdWk0MEdnMmR5ZVpDMzhsZklPdXJZdDNxakV6L08wOENmTUFsTmc0elcxU3ZxcjJ0MFF3dWpDM2dpckpDc0JJQ0w2RVQxVmFyaXFOcjFjV2FtRHpWNnlORUQvUTFTWmdCSHRLMitScjF0dUttU0ZZMjl6cUgvNW93Z2pWS0FnaVFBTHJ2WG82UG1lRGkwcm9QaVdIcmpiTGFDb0dYaXFKcWZjc3Q2b0EwTUNFd29uaUVlbmF1c2NSOFFqdE9CS0dCWmtjc3NZTW1MTkl3c0tkWmF4N1pKTi82b2c5c21RdHZuYWdRb0RDMENBRHorenB3Y0lMZ3RwdFZqbnhSTDh2VmM0clN0ckNuSk4wbmZhQyszL2lJUDZIUnd2YXMwdkZ0dFJ3enIvTWtubHhlNWFxVEhwdjFkQzYwVmFkSkMyMjdRWDJvckM4ekZxOVhmNDZ0MzJYeWptN1crSjJSNTNaNUdlZjNBZTVtN0ZRTGNlZzIrY1ltY3RpLzlYa1RwbjRDRXFjdGF5dThUdUlKUGRscnA1aTNrcWtoN1JmZFpoblZkdFc0QmNPVUIxNkxkeU1tWmFxVUpoQitTdlkrN2N6VmFZeGg4d1pSRU16MHBNalF0ZTJSSVRPaWpBdisweXR2Qit5TjM0a0ZjRThudDJDbkV5Tm03azFXMFhtRlpxY055R216YnIyWmZhaXhFeE1QZWxYS29TV1hRWmRNblRWR1FjTGhka05rY3ZXVzdzVVhYZXZiMGRlYzZXUWJwNTBMQVVkM2d3RS92VkxJRm9qSkNvaHQrVE9ROHBZMlpzMnhKNXdKVW5JZm1qUjBJRjdBRjJRNUFoWG96RVVFY2lmdzF1amdQTEpXWWhCUHZMUjRGdUppRjYwWUxreHdiRHNUSUl5OSttMysydkdzSDAzU3l6ZFpPMklEa1VpMnQ4c2YwOUhoV0ZKblRDUloxMTZWN0NsdGphWk1WclNLV0k2bzY1Y2FvZ2dmZTQrUXl3Zk5SYlVOK3NkZXhVbXdubnB4MDV4QjVZT241R29lSFdxUCtxT1FteUIvSDZJTUJrOFYvL0FzYXo5YU9YMnJQeHNCaW9SRzA3TjhWTVd3TkFQa0xrR1ZFV0NVR3pEbU9SQjBIcGJmWEtpWDdlN1VDcGRtWFZleUwwVExGaFNid0dMSENKNGJ1Rjkzczd6RldrTER6NVlyejNhd0g0UEdZclNUaUI5Y3NERUpMOFd5Rm9RWnVmSkRmbzlhMEk5MExXVVFaNW5wOGwrOXhUNU9NSmFLZnBOZTNwM2swN09uZnZsTW5UZzhnYkJEQ0Fta2FrYkkrR2pUQlJmUTVoaWtlU2JtMk0rNWlJTG5aUlNqbTZrRTZOK21EbFRQaUtaZlNYT21BT1lreHJxNGxTSFRhSGt5SGFEcHQ4dHBVRjlSeGlTdWNIQzAvelRtTk5xRjRKNlZSc2N2RUwvamhpOE4xSXllS0hqeUVzUmV3NUx0cllndnV1YW13UFNyOWJWbTdsNGFqcUhhUUFxQ09XRWIvWHVCOSt3azFwMWk2WWkraGhtT3ZUZVdhYmk4L0d3L0J2UXBmUjVLbC84OVc5RHY2ZDYxU3pDcTAwRFRabkpzeXAxVGN2dDdpZHIrQmtuVmF1WE43NWtyTTBiQXd1eGdsdzBhYWZKVld1eTJPWmpSbWVaa1ovRVB3aUYwOXdCSWpJVGZOVUV5VTAwVWhLSkd1Qnk4M1RJSWhqcmJqK0Y0N0ZNR0hSc2UvWTU3bEJXbzkvOHJESmNVVVg5RXRnRUowLzMyVTM1ZWg1NERrQmlsU2h1OFg5ZGtxaGc3M0NrQ1VLQmpXZDRVZGhVNko5RXRIYjlkVGRKVStwQWtZaGhHZXNhZGtaYVBMWEpWVytDSUN6a3FQUWhwejhMeGFMOTBBd3hqdHNQeFRxRUZIUHlhSjNEbWVkNWN2dnBvTHFLQTdJbSsxdVREeENZUmZ4TnBsZkRpYWR1OGs1aEJHT2hiOStoNHpMWWlDcjJSM0ZuZEZ4NUNVL3JMbVVLaFRIdm9KaENFZTNKTGZaWjJFcis3ZHVGMUNDUkVCemlIUXB6eEQrS3hJcWYyREFjYytZIiwibm9uY2UiOiJWTFN4dS8rNWpnQ2x4aUlMIn0= \
  --device-backup-key kwyITE+VlpVBSUtlPG4xegqvuKMwtw6EtnlEJQnKWtw= \
  --platform-backup-type key-share \
  --chain-code Z6EN3ZNVJzocT9IrzJvJYChBfloi3phAB8dKhjIkKHE= \
  --platform-backup-private-key-mnemonic "ride rely ill market rapid educate nest kidney legal edit improve useless" \
  --platform-backup-private-key-mnemonic "palace utility good more suggest crack spoon help return moment swamp man" \
  --platform-encrypted-share eyJlbmNyeXB0ZWRfc2Vzc2lvbl9rZXkiOiJwN29iTjJobS9hWEhlczNwNXJjVzBqZEVmYzZ1QzE4NXhWYzVYTmh1YWMwZGRZSDBWSDRFNDFxWnVxemMwSVhhUmdxZERMREdWOWxyOE1rdjZSRzEvNVU4NWFaSWJ1WXZlZHViTDF0K3BBZWhVaWt4dG5naU0yRnJmeThDVW1HL1NISkN1MHFxeDdIWU9OUEFmUjlzM1BYZTFvUDVQUUIyTWY4Q05xNmZnbmdjc2RoUXFmNWNZSWRHN3BOMnNNYW4wREJiNHIxL0IyaDdpVXZ1d0swWmJEbllMRWhocGc1NlR0bnQwbk5UbkFrVHhodGh0Mm0vUyt3R3JLdjZnMjA0dlJEdFlRTDMwcVFYSGFlN0Uvc3l3dENhZ1RtdmJSR0NNRFp0NnFWSHFmenUvU1F2bEdYVnRRRXRBWDZDbGlHM1ptdkpGU04rdXVMeXVIa0tyK0tPUmc9PSIsIm5vbmNlIjoiSzEzNnFlcW05QW1mUENmKyIsImNpcGhlcnRleHQiOiJjN1NRam5EZndCMi9HQXRROXhhS2NyVFl3ZHhmbWZKeEQwNkNsd1dONlRnZE1DanIxdVd6SURZZmhDOWlvdmx1MGFtcEdzanpLQU1vVEdrMllwcEw0aTFocTVXYjhaRms1Tlk9In0= \
  --platform-encrypted-share eyJlbmNyeXB0ZWRfc2Vzc2lvbl9rZXkiOiJLWUNwMzN1b3dCSFZscWZFYnNsQndNc3psNDV1WU1BZzQwRTh0TDdkNEFaMFVmUnliUXI2QnlrQnFPSm5xVWxmbWczeEwwTGZyU0t2aGJodlVGZkdndzRKUE1ra0l5Z3VobHBJS3RkNTFSSTRmRlNINmloeXlLRFhPTnpZTWdpRjRZT282cDRXczJGbU1yNlhiVTFMSlVkSDB3dzh4SDcxcGptVzJSd1RjVUVXLzQzTk9aS3gxc1ZOVVBhZjQ1TlByUnZ0dmpFZGxBU2xEYjdzbDdyNDlWaFJUYW1KU2FTME80T2N4eFVxUWRINUpwN1Vvbk1sWjNrTGFzczJJSk8zTXBlTHYrMkE0dHBvV3JXc1dSNllSdUZISktRMDRhd2p5UTF6UGoyeEROMHRxdnpySHJKZmdORjdlWlNPaTBvcDJCb2JGNlQvbDVvUXQzZmt2WnJjRFE9PSIsIm5vbmNlIjoiSUZoNElXNnNZK1Z3c1FWeiIsImNpcGhlcnRleHQiOiJ5eng0eUFCUTdSOHA4ZVBKWDllcHk0a0tFbU9SeVFrMVJDSURCQlpyVGJtTGpoS0U3NnpFc0ZyZ2tuUDlaYkVZU0h5eVhzcUR2Q2VVT1VDV3pGNlh5Z1JKTWxBOFdoL2pSV0E9In0=