|
| 1 | +--- |
| 2 | +title: Encrypt results and decrypt them |
| 3 | +description: |
| 4 | + Learn how to encrypt iApp results end-to-end and decrypt them locally using |
| 5 | + the iExec SDK |
| 6 | +--- |
| 7 | + |
| 8 | +# 🔐 Encrypt Results and Decrypt Them |
| 9 | + |
| 10 | +Secure your outputs with end‑to‑end encryption so only you (the beneficiary) can |
| 11 | +read them. Results leave the enclave and may traverse untrusted storage and |
| 12 | +networks; encryption ensures nobody else (operators, storage providers, |
| 13 | +intermediaries) can access the content. In this guide, you will generate a key |
| 14 | +pair, publish the public key to the Secret Management Service (SMS) — which |
| 15 | +provides it at runtime to the enclave running your iApp — run tasks with |
| 16 | +encrypted results, and download and decrypt them locally. |
| 17 | + |
| 18 | +::: info You don't need to change your application's code or redeploy it to add |
| 19 | +this feature. ::: |
| 20 | + |
| 21 | +## Prerequisites |
| 22 | + |
| 23 | +Before you begin, make sure you have the iExec SDK installed. |
| 24 | + |
| 25 | +::: code-group |
| 26 | + |
| 27 | +```sh [npm] |
| 28 | +npm install iexec |
| 29 | +``` |
| 30 | + |
| 31 | +```sh [yarn] |
| 32 | +yarn add iexec |
| 33 | +``` |
| 34 | + |
| 35 | +```sh [pnpm] |
| 36 | +pnpm add iexec |
| 37 | +``` |
| 38 | + |
| 39 | +```sh [bun] |
| 40 | +bun add iexec |
| 41 | +``` |
| 42 | + |
| 43 | +::: |
| 44 | + |
| 45 | +## 1) Generate your encryption key pair |
| 46 | + |
| 47 | +The beneficiary key pair is the root of trust for result confidentiality. The |
| 48 | +public key will be used inside the TEE to encrypt results for the beneficiary; |
| 49 | +the private key stays with the beneficiary to decrypt them locally. |
| 50 | + |
| 51 | +Run from your iExec project directory: |
| 52 | + |
| 53 | +```bash |
| 54 | +iexec result generate-encryption-keypair |
| 55 | +``` |
| 56 | + |
| 57 | +This creates two files in `.secrets/beneficiary/`: |
| 58 | + |
| 59 | +``` |
| 60 | +.secrets/ |
| 61 | +└─ beneficiary/ |
| 62 | + ├─ <0x-your-wallet-address>_key # PRIVATE KEY (keep safe) |
| 63 | + └─ <0x-your-wallet-address>_key.pub # PUBLIC KEY |
| 64 | +``` |
| 65 | + |
| 66 | +Back up the private key securely. You will only need it locally to decrypt |
| 67 | +results. |
| 68 | + |
| 69 | +## 2) Push your public key to the SMS |
| 70 | + |
| 71 | +The Secret Management Service securely delivers your public key, at runtime, to |
| 72 | +the enclave running your iApp. Without this, the iApp cannot encrypt outputs for |
| 73 | +you. |
| 74 | + |
| 75 | +Make the public key available to TEEs at runtime: |
| 76 | + |
| 77 | +```bash |
| 78 | +iexec result push-encryption-key --tee-framework scone |
| 79 | +``` |
| 80 | + |
| 81 | +Verify it: |
| 82 | + |
| 83 | +```bash |
| 84 | +iexec result check-encryption-key --tee-framework scone |
| 85 | +``` |
| 86 | + |
| 87 | +## 3) Run the iApp with encrypted results |
| 88 | + |
| 89 | +The --encrypt-result flag instructs the platform to perform envelope encryption |
| 90 | +inside the enclave using your public key, so the archive that leaves the TEE is |
| 91 | +unreadable to others. |
| 92 | + |
| 93 | +Trigger a task and request encrypted outputs: |
| 94 | + |
| 95 | +```bash |
| 96 | +iexec app run <0x-app-address> \ |
| 97 | + --workerpool <0x-workerpool-address> \ |
| 98 | + --tag tee,scone \ |
| 99 | + --encrypt-result \ |
| 100 | + --watch |
| 101 | +``` |
| 102 | + |
| 103 | +When completed, download the results archive: |
| 104 | + |
| 105 | +```bash |
| 106 | +iexec task show <0x-task-id> --download |
| 107 | +``` |
| 108 | + |
| 109 | +Inside the archive, `iexec_out/result.zip.aes` is encrypted. |
| 110 | + |
| 111 | +Note: Results are encrypted for the task beneficiary. Ensure the beneficiary |
| 112 | +address is yours to be able to decrypt the archive. |
| 113 | + |
| 114 | +If you extract the archive and try to read the encrypted file, you'll see |
| 115 | +unreadable content: |
| 116 | + |
| 117 | +```bash |
| 118 | +mkdir /tmp/trash && \ |
| 119 | + unzip <0x-your-task-id>.zip -d /tmp/trash && \ |
| 120 | + cat /tmp/trash/iexec_out/result.zip.aes |
| 121 | +``` |
| 122 | + |
| 123 | +The output will look like: |
| 124 | + |
| 125 | +```bash |
| 126 | +)3XqYvzEfRu<\ݵmm疞rc(a{{'ܼ͛q/[{hgD$g\.kj"s?"hJ_Q41_[{XԚa蘟vEr肽 |
| 127 | +Յ]9WTL*tdzO`!e&snoL3K6L9% |
| 128 | +``` |
| 129 | +
|
| 130 | +This confirms the results are properly encrypted and unreadable without the |
| 131 | +private key. |
| 132 | +
|
| 133 | +## 4) Decrypt results locally |
| 134 | +
|
| 135 | +Results are encrypted end‑to‑end; only your private key can decrypt them. This |
| 136 | +step restores the plaintext so you can use the output files. |
| 137 | +
|
| 138 | +Use your private key generated in step 1: |
| 139 | +
|
| 140 | +```bash |
| 141 | +iexec result decrypt iexec_out/result.zip.aes |
| 142 | +``` |
| 143 | +
|
| 144 | +This produces `results.zip`. Extract it to view plaintext outputs: |
| 145 | +
|
| 146 | +```bash |
| 147 | +unzip results.zip -d my-decrypted-result |
| 148 | +``` |
| 149 | +
|
| 150 | +And you can see the content of your result file: |
| 151 | +
|
| 152 | +```bash |
| 153 | +$ cat my-decrypted-result/result.txt |
| 154 | +Hello, world! |
| 155 | +``` |
| 156 | +
|
| 157 | +Your results are now decrypted and ready to use. |
| 158 | +
|
| 159 | +## Notes and tips |
| 160 | +
|
| 161 | +- Keep the private key offline and backed up. |
| 162 | +- You can rotate keys by re-running generation and push steps; old tasks remain |
| 163 | + decryptable with the old private key. |
| 164 | +- iApp code does not need changes to enable result encryption; it is enforced by |
| 165 | + the TEE using the public key from SMS. |
| 166 | +
|
| 167 | +## Related guides |
| 168 | +
|
| 169 | +- [Outputs](/guides/build-iapp/outputs) - Learn how to generate proper outputs |
| 170 | + from your iApp |
| 171 | +- [Run iApp with ProtectedData](/guides/use-iapp/run-iapp-with-ProtectedData) - |
| 172 | + Execute iApp with encrypted data inputs |
| 173 | +- [Run iApp without ProtectedData](/guides/use-iapp/run-iapp-without-ProtectedData) - |
| 174 | + Basic iApp execution methods |
| 175 | +- [How to Pay for Executions](/guides/use-iapp/how-to-pay-executions) - |
| 176 | + Understanding costs and payment options |
| 177 | +- [iApp Generator](/references/iapp-generator) - Build your own confidential |
| 178 | + computing applications |
0 commit comments