Skip to main content

Getting Wrapped Key Metadata

This guide covers the getEncryptedKey function from the Wrapped Keys SDK. For an overview of what a Wrapped Key is and what can be done with it, please go here.

The getEncryptedKey function allows you to request a Wrapped Key's metadata stored within Lit's private DynamoDB instance. Covered in detail further in this guide, the metadata includes properties such as the encrypted private key's ciphertext and dataToEncryptHash that could be used to decrypt the key outside of the Wrapped Key Lit Actions.

Below we will walk through an implementation of getEncryptedKey. The full code implementation can be found here.

Overview of How it Works​

  1. The Wrapped Keys SDK will use the provided Wrapped Key ID and PKP Session Signatures to fetch the stored metadata for a specific Wrapped Key from the Wrapped Keys backend service
  2. The stored metadata is returned as a StoredKeyData object

Prerequisites​

Before continuing with this guide, you should have an understanding of:

getEncryptedKey's Interface​

Source code

import { LIT_NETWORKS_KEYS } from '@lit-protocol/types';

/** Get a previously encrypted and persisted private key and its metadata.
 * Note that this method does _not_ decrypt the private key; only the _encrypted_ key and its metadata will be returned to the caller.
 */
export async function getEncryptedKey(
  params: {
    pkpSessionSigs: SessionSigsMap;
    litNodeClient: ILitNodeClient;
    id: string,
  }
): Promise<{
  ciphertext: string;
  dataToEncryptHash: string;
  publicKey: string;
  pkpAddress: string;
  keyType: string;
  litNetwork: LIT_NETWORKS_KEYS;
  memo: string;
  id: string;
}>

Parameters​

pkpSessionSigs​

When a Wrapped Key is generated, it's encrypted with the following Access Control Conditions:

[
    {
        contractAddress: '',
        standardContractType: '',
        chain: CHAIN_ETHEREUM,
        method: '',
        parameters: [':userAddress'],
        returnValueTest: {
        comparator: '=',
        value: pkpAddress,
        },
    },
];

where pkpAddress is the addressed derived from the pkpSessionSigs. This restricts the decryption of the Wrapped Key to only those whom can generate valid Authentication Signatures from the PKP which generated the Wrapped Key.

A valid pkpSessionSigs object can be obtained using the getPkpSessionSigs helper method available on an instance of LitNodeClient. We dive deeper into obtaining a pkpSessionSigs using getPkpSessionSigs in the Generating PKP Session Signatures section of this guide.

litNodeClient​

This is an instance of the LitNodeClient that is connected to a Lit network.

id​

This is a unique identifier (UUID v4) generated by Lit for the Wrapped Key.

Because a PKP can have multiple Wrapped Keys attached to it, this ID is used to identify which Wrapped Key to use when calling other Wrapped Key methods such as signMessageWithEncryptedKey and signTransactionWithEncryptedKey.

Return Value​

ciphertext​

This return value is the encrypted form of the underlying private key for the Wrapped Key associated with the PKP that produced pkpSessionSigs.

Used with the dataToEncryptHash, Access Control Conditions, and pkpSessionSigs, you can decrypt the ciphertext to get the clear text private key.

dataToEncryptHash​

This is the SHA-256 hash of the ciphertext.

Used with the ciphertext, Access Control Conditions, and pkpSessionSigs, you can decrypt the ciphertext to get the clear text private key.

publicKey​

This is the corresponding public key for the underlying private key for the Wrapped Key.

pkpAddress​

This is the Ethereum address for the PKP that is associated with the Wrapped Key i.e. the PKP that created the Session Signatures when the Wrapped Key was imported/generated, and used for encrypting the private key. The address is derived from the provided pkpSessionSigs.

keyType​

This is the algorithm used to generate the underlying private key for the Wrapped Key.

litNetwork​

This is the Lit network that the LitNodeClient was connected to when the Wrapped Key was created.

memo​

This is the additional identifier/descriptor string set for the Wrapped key when it was imported, generated, or stored.

This parameter is an arbitrary string that can be used as an additional identifier or descriptor of the encrypted private key.

id​

This is a unique identifier (UUID v4) generated by Lit for the Wrapped Key.

Because a PKP can have multiple Wrapped Keys attached to it, this ID is used to identify which Wrapped Key to use when calling other Wrapped Key methods such as signMessageWithEncryptedKey and signTransactionWithEncryptedKey.

Example Implementation​

Now that we know what the getEncryptedKey function does, it's parameters, and it's return values, let's now dig into a complete implementation.

The full code implementation can be found here.

Installing the Required Dependencies​

npm install \
@lit-protocol/auth-helpers \
@lit-protocol/constants \
@lit-protocol/lit-auth-client \
@lit-protocol/lit-node-client \
@lit-protocol/wrapped-keys \
ethers@v5

Instantiating an Ethers Signer​

The ETHEREUM_PRIVATE_KEY environment variable is required. The corresponding Ethereum address needs to have ownership of the PKP we will be using to generate the pkpSessionSigs. 

import * as ethers from 'ethers';
import { LIT_RPC } from "@lit-protocol/constants";

const ethersSigner = new ethers.Wallet(
    process.env.ETHEREUM_PRIVATE_KEY,
    new ethers.providers.JsonRpcProvider(LIT_RPC.CHRONICLE_YELLOWSTONE)
);

Instantiating a LitNodeClient​

Here we are instantiating an instance of LitNodeClient and connecting it to the datil-dev Lit network.

import { LitNodeClient } from "@lit-protocol/lit-node-client";
import { LIT_NETWORK } from "@lit-protocol/constants";

const litNodeClient = new LitNodeClient({
    litNetwork: LIT_NETWORK.DatilDev,
    debug: false,
});
await litNodeClient.connect();

Generating PKP Session Signatures​

The LIT_PKP_PUBLIC_KEY environment variable is required. This PKP should be owned by the corresponding Ethereum address for the ETHEREUM_PRIVATE_KEY environment variable.

The PKP's Ethereum address will be used for the Access Control Conditions used to encrypt the generated private key, and by default, will be the only entity able to authorize decryption of the private key.

note

The expiration used for the Auth Method must be 10 minutes or less to be valid.

note

The Auth Method used in this example implementation is signing a Sign in With Ethereum (EIP-4361) message using an Externally Owned Account (EOA), but any Auth Method can be used to authenticate with Lit to get PKP Session Signatures.

import { EthWalletProvider } from "@lit-protocol/lit-auth-client";
import { LIT_ABILITY } from "@lit-protocol/constants";
import {
  LitActionResource,
  LitPKPResource,
} from "@lit-protocol/auth-helpers";

const pkpSessionSigs = await litNodeClient.getPkpSessionSigs({
    pkpPublicKey: process.env.LIT_PKP_PUBLIC_KEY,
    authMethods: [
        await EthWalletProvider.authenticate({
            signer: ethersSigner,
            litNodeClient,
            expiration: new Date(Date.now() + 1000 * 60 * 10).toISOString(), // 10 minutes
        }),
    ],
    resourceAbilityRequests: [
    {
        resource: new LitActionResource("*"),
        ability: LIT_ABILITY.LitActionExecution,
    },
    ],
    expiration: new Date(Date.now() + 1000 * 60 * 10).toISOString(), // 10 minutes
});

Getting a Wrapped Key's Metadata​

Now that we hall all that we need, we can call getEncryptedKey to get the metadata for the Wrapped key.

import { api } from "@lit-protocol/wrapped-keys";

const { getEncryptedKey } = api;

const wrappedKeyMetadata = await getEncryptedKey({
    pkpSessionSigs,
    litNodeClient,
    id: process.env.WRAPPED_KEY_ID
});

Summary​

The full code implementation can be found here.

After executing the example implementation above, you will have exported the metadata for the Wrapped Key that was associated with the PKP that produced the provided pkpSessionSigs, and had the provided id.