Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Decrypt and Combine Rework #336

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Decrypt and Combine Rework #336

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0b862af
Summary
awisniew207 Sep 12, 2024
e7ff668
Grammar and content changes
awisniew207 Sep 12, 2024
dd2b13a
Reordering content
awisniew207 Sep 12, 2024
579a470
Update docs/sdk/serverless-signing/combining-decryption-shares.md
spacesailor24 Sep 14, 2024
294f2b6
Update docs/sdk/serverless-signing/combining-decryption-shares.md
spacesailor24 Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 66 additions & 86 deletions docs/sdk/serverless-signing/combining-decryption-shares.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,99 +4,79 @@ import FeedbackComponent from "@site/src/pages/feedback.md";

## Overview

Decryption with Lit is typically performed client-side by an authorized user at the time of access. This process is documented [here](../access-control/quick-start.md). However, an alternative method of decryption is supported using Lit Actions. Specifically, the `decryptAndCombine` function can be used to decrypt data within a Lit Action. This is useful for performing operations over sensitive data, where the data itself remains private within the confines of each Lit node's Trusted Execution Environment (TEE). You can learn more about Lit's architecture [here](../../resources/how-it-works#sealed-and-confidential-hardware.md).

When you call `decryptAndCombine`, each Lit node's decryption shares are collected and combined on a single node and used to decrypt the given content.

The following doc will provide a complete walkthrough of using `decryptAndCombine`. We'll start by encrypting a string client-side before using a Lit Action to decrypt it. At the bottom of the page you'll find a complete example that demonstrates how you can use this functionality to decrypt an API key and perform a remote API call from within an Action.

# Encrypting content
The first step is to encrypt your data. The encryption operation will be performed client-side *outside* of your Lit Action using the `LitNodeClient`:

```js
const chain = 'ethereum';
const accessControlConditions = [
{
contractAddress: '',
standardContractType: '',
chain,
method: 'eth_getBalance',
parameters: [':userAddress', 'latest'],
returnValueTest: {
comparator: '>=',
value: '0',
},
},
];
const message = 'Hello world';
const client = new LitNodeClient({
litNetwork: "datil-dev"
});
await client.connect();
const { ciphertext, dataToEncryptHash } = await LitJsSdk.encryptString(
{
accessControlConditions,
sessionSigs: {}, // your session
chain,
dataToEncrypt: message,
},
client
);

console.log("cipher text:", ciphertext, "hash:", dataToEncryptHash);
```
Let's break this down. The first step was creating your Access Control Condition (ACC), which is used to specify who or under what conditions your data should be able to be decrypted.

The second step was actually encrypting the static content (string, file, zip, etc...) using the `encryptString` function. This returns a `ciphertext` and `dataToEncryptHash`. The `ciphertext`, `dataToEncryptHash`, chain data, and any other metadata (such as your `accessControlConditions`) should be stored on your storage provider of choice. A solid choice is IPFS.

## Using IPFS CID as an Access Control Parameter
For this example, you can set your Access Control parameter as `currentActionIpfsId` which can be accomplished using the snippet below. This will mean that only a specific Lit Action (based on the IPFS CID where it has been deployed) will be able to decrypt your data. No other party will ever have access. This is useful for situations where you want to restrict access to sensitive information, like an API key, so that it can only be decrypted by a specific Lit Action.

```js
{
contractAddress: '',
standardContractType: '',
chain: 'ethereum',
method: '',
parameters: [':currentActionIpfsId'],
returnValueTest: {
comparator: '=',
value: '<YOUR_LIT_ACTION_IPFS_CID>',
},
}
```
Decryption with Lit can be performed either client-side by an authorized user or within a Lit Action.

Using decryption within a Lit Action is useful for performing operations over sensitive data, where the data itself remains private within the confines of each Lit node's Trusted Execution Environment (TEE). You can learn more about Lit's architecture [here](../../resources/how-it-works#sealed-and-confidential-hardware.md).

Lit Actions have two methods for decrypting data: `decryptToSingleNode` and `decryptAndCombine`.

As the name implies, `decryptToSingleNode` will request the signature shares from all the Lit node in the network and will combine them only within a single Lit node. This means the fully decrypted data will only exist within a single Lit node's TEE.

`decryptAndCombine` runs on every Lit node in the network, requesting signature shares from all the other nodes and combining them within each Lit node's TEE. This means the fully decrypted data will exist within all the Lit nodes TEE, and an error will be thrown by the network if the Lit nodes do not reach consensus on the decrypted data.

## Using decryptAndCombine
When `decryptToSingleNode` is used, the execution scope being reduced to a single Lit node means that any behavior that requires multiple nodes (i.e. console logs, `signAndCombineEcdsa`) will encounter a timeout error.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When you say console logs, do you mean console.log? I don't think there's an affect on these when running within a single node?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add a snippet on how to end execution on all the Lit node that weren't selected for the decryption

That looks something like this


We can now use the `ciphertext` and `dataToEncryptHash` that we got earlier during the encryption step and pass it into our Lit Action.
The following example demonstrates how to encrypt an API key client-side, then decrypt and use it within a Lit Action to query the block number on Base.

In the below example we set the `authSig` to `null` as a way to tell the Lit Action runtime to use the `authSig` which was provided to the node when you call `executeJs` which returns `sessionSigs`. If you wish you may provide a different Auth Signature if the one provided from the session is not relevant to your use case. You can learn more about authentication and creating session signatures using these [docs](../authentication/session-sigs/intro.md).
## Prerequsites
- Knowledge of [SessionSigs](../authentication/session-sigs/intro)
- Basic understanding of [Lit Actions](../serverless-signing/quick-start)
- Intermediate understanding of Lit [Encryption and Decryption](../access-control/quick-start)

```js
const code = `(async () => {
const resp = await Lit.Actions.decryptAndCombine({
accessControlConditions,
ciphertext,
dataToEncryptHash,
authSig: null,
chain: 'ethereum',
});
## Complete Code Example
The complete code example is available in the [Lit Developer Guides Code Repository](https://github.com/LIT-Protocol/developer-guides-code/tree/master/decrypt-api-key-in-action/nodejs).

Lit.Actions.setResponse({ response: resp });
})();`
### Example Lit Action

const res = await client.executeJs({
code,
sessionSigs: {} // your session
jsParams: {
accessControlConditions,
ciphertext,
dataToEncryptHash
The `decryptAndCombine` function uses the `accessControlConditions` to specify who and under what conditions the data can be decrypted. The `ciphertext` and `dataToEncryptHash` are the encrypted data and the hash of the data that was encrypted.

We set the `authSig` to `null` as a way to tell the Lit Action runtime to use the `authSig` which was provided to the node when `executeJs` was called; The AuthSig is sourced from the session signatures.

Then our decrypted API key is used to query the blocknumber on Base.

```tsx
const _litActionCode = async () => {
try {
const apiKey = await Lit.Actions.decryptAndCombine({
accessControlConditions,
ciphertext,
dataToEncryptHash,
authSig: null,
chain: "ethereum",
});

const fullUrl = url + apiKey;

const resp = await fetch(fullUrl, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "eth_blockNumber",
params: [],
}),
});

let data = await resp.json();

if (data.result) {
data.result = parseInt(data.result, 16);
}
});

console.log("decrypted content sent from lit action:", res);
Lit.Actions.setResponse({ response: JSON.stringify(data) });
} catch (e) {
Lit.Actions.setResponse({ response: e.message });
}
};

export const litActionCode = `(${_litActionCode.toString()})();`;
```

## Complete Example: Decrypting an API Key From Within an Action
The following example demonstrates how you can decrypt an API key within a Lit Action. Once decrypted, the API key can be used to perform a remote API call. Check out the complete code example [here](https://github.com/LIT-Protocol/developer-guides-code/tree/master/decrypt-api-key-in-action).
## Summary

This guide demonstrates how to use Lit Actions to decrypt data within a Lit Action.

If you'd like to learn more about Lit Actions, check out the [Lit Actions SDK](https://actions-docs.litprotocol.com/), or our [Advanced Topics](https://developer.litprotocol.com/category/advanced-topics-1) section on Lit Actions.