diff --git a/docs/getting-started/export.md b/docs/getting-started/export.md new file mode 100644 index 0000000..d562ec6 --- /dev/null +++ b/docs/getting-started/export.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 8 +description: Learn about Export on Turnkey +slug: /getting-started/export +--- +# Export + +Exporting a [Wallet](./wallets.md) or [Private Key](./wallets.md#private-keys) lets a user securely view their wallet as a mnemonic. This can be helpful for backup or transfer purposes. + +## Cryptographic details + +Turnkey's export functionality ensures that neither your application nor Turnkey can view the wallet mnemonic or private key. The following diagram summarizes the flow: + + + +Our export flow works by anchoring export in a **target encryption key** (TEK). This target encryption key is a standard P-256 key pair and can be created in many ways: completely offline, or online inside of script using the web crypto APIs. + +The public part of this key pair is passed as a parameter inside of a signed `EXPORT_WALLET` or `EXPORT_PRIVATE_KEY` activity. + +Our enclave encrypts the wallet's mnemonic or raw private key to the user's TEK using the **Hybrid Public Key Encryption standard**, also known as **HPKE** or [RFC 9180](https://datatracker.ietf.org/doc/rfc9180/). + +Once the activity succeeds, the encrypted mnemonic or private key can be decrypted by the target public key offline or in an online script. \ No newline at end of file diff --git a/docs/integration-guides/export-wallets.md b/docs/integration-guides/export-wallets.md new file mode 100644 index 0000000..ae85e7d --- /dev/null +++ b/docs/integration-guides/export-wallets.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 3 +description: Learn about Wallet Export on Turnkey +slug: /integration-guides/export-wallets +--- +# Export Wallet + +Exporting a [Wallet](../getting-started/wallets.md) allows your users to back up or transfer a wallet by securely viewing the wallet's [mnemonic](https://learnmeabitcoin.com/technical/mnemonic). We engineered this feature to ensure that the user can export their mnemonic without needing you in the loop. + +## Before you start +Make sure you have created a wallet for your user. +Check out our [Quickstart guide](../getting-started/Quickstart.md) if you need help getting started. + + +If you'd like to use a sub-organization as a wallet for your user, follow our [Wallet integration guide](./sub-organizations-as-wallets.md). + + +## Helper packages + +* We have released open-source code to create target encryption keys and decrypt exported wallet mnemonics. We've deployed this a static HTML page hosted on `export.turnkey.com` meant to be embedded as an iframe element (see the code [here](https://github.com/tkhq/frames)). This ensures the mnemonics are encrypted to keys that the user has access to, but that your organization does not (because they live in the iframe, on a separate domain). +* We have also built a package to help you insert this iframe and interact with it in the context of export: [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) + +In the rest of this guide we'll assume you are using these helpers. + +## Export step-by-step + +Here's a diagram summarizing the wallet export flow step-by-step ([direct link](/img/wallet_export_steps.png)): + + + +Let's review these steps in detail: + +1. User on `yoursite.xyz` clicks "export", and a new export UI is shown. We recommend this export UI be a new hosted page of your site or application, which contains language explaining to the user the security best practices they should follow once they've successfully exported their wallet. While the UI is in a loading state, your frontend uses [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) to insert a new iframe element: + ```js + const iframeStamper = new IframeStamper({ + iframeUrl: "https://export.turnkey.com", + // Configure how the iframe element is inserted on the page + iframeContainerId: "your-container", + iframeElementId: "turnkey-iframe", + }); + + // Inserts the iframe in the DOM. This creates the new encryption target key + const publicKey = await iframeStamper.init(); + + // Set state to not display iframe + let showIframe = false; + + return ( + // The iframe element can be hidden until the wallet is exported +
+ ); + ``` +2. Your code receives the iframe public key. Your app prompts the user to sign a new `EXPORT_WALLET` activity with the wallet ID and the iframe public key in the parameters. +3. Your app polls for the activity response, which contains an export bundle. Remember: this export bundle is an encrypted mnemonic which can only be decrypted within the iframe. +4. Your app injects the export bundle into the iframe for decryption and displays the iframe upon success: + ```js + // Inject export bundle into iframe + let success = await iframeStamper.injectWalletExportBundle(exportBundle); + + if (success !== true) { + throw new Error("unexpected error while injecting export bundle"); + } + + // If successfully injected, update the state to display the iframe + showIframe = true; + ``` + +Export is complete! The iframe now displays a numbered 3-column grid of words that form the mnemonic. + +## UI customization + +To enable as much customization of brand, theme, and copy, we've limited the only non-customizable UI component in the export iframe to be the grid of words forming the mnemonic. + +## Private Keys + +Turnkey also supports exporting raw private keys. To implement export for private keys, follow the same [steps](#export-step-by-step) above, but instead use the `EXPORT_PRIVATE_KEY` activity and the `injectKeyExportBundle` method on the [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper). At the end of a successful private key export, the iframe displays a hexadecimal-encoded raw private key. diff --git a/static/img/wallet_export_cryptography.png b/static/img/wallet_export_cryptography.png new file mode 100644 index 0000000..43c1ee6 Binary files /dev/null and b/static/img/wallet_export_cryptography.png differ diff --git a/static/img/wallet_export_steps.png b/static/img/wallet_export_steps.png new file mode 100644 index 0000000..e3e0ac8 Binary files /dev/null and b/static/img/wallet_export_steps.png differ