Skip to main content

Overview

Wrapped Keys are a secure and flexible key management solution provided by Lit Protocol. They offer a unique approach to handling private keys, combining the security of encryption with the programmability of Lit Actions to offer private key signing to a broader range of blockchain networks.

Using Wrapped Keys, you can sign arbitrary data and transactions (optionally broadcasting the signed transaction to a blockchain network) using a private key which is only decrypted within a single Lit node's Trusted Execution Environment (TEE).

Unlike Programmable Key Pairs (PKPs), the signing logic for Wrapped Keys is implemented completely within a Lit Action, allowing the use of third-party libraries to perform the signing operation. This provides signing capability using the Lit Protocol to any blockchain network you can implement the signing logic for within a Lit Action.

Key Features​

  • Secure Storage: Encrypted and stored in Lit's private DynamoDB instance ensures key safety at rest.
  • TEE Protection: Keys are only decrypted within a single Lit node's Trusted Execution Environment (TEE).
  • PKP Access Control: Each Wrapped Key is linked to a PKP that controls the authorization to decrypt the private key for usage.
  • Flexible Signing Logic: Unlike PKPs, signing logic for Wrapped Keys is implemented entirely within a Lit Action, allowing for custom implementations and the use of third-party libraries.
  • Wide Compatibility: Support for various cryptographic curves and blockchains, extending Lit Protocol's capabilities to any network with JavaScript signing libraries.

The Synergy of Wrapped Keys and PKPs​

A crucial aspect of Wrapped Keys is their integration with PKPs. While Wrapped Keys and PKPs serve different purposes, they work together to provide a comprehensive key management and access control system:

  • Wrapped Keys: Store and manage the actual private keys used for signing operations.
  • PKPs: Control authorization to decrypt Wrapped Keys for usage.

Every Wrapped Key is linked to a specific PKP. This PKP acts as a gatekeeper, managing the authorization required to decrypt and use the Wrapped Key. This synergy allows for sophisticated access control while maintaining the flexibility of Wrapped Keys.

How it Works​

Key Generation and Storage​

When generating a new Wrapped Key, or initializing one by importing an existing private key, the process involves several steps:

  1. The Wrapped Keys SDK derives a PKP's Ethereum address from the provided PKP Session Signatures.
  2. The private key (generated or imported) is encrypted using the Lit network's public BLS key.
  3. Access Control Conditions are set, allowing only the derived PKP Ethereum address to decrypt the key.
  4. The resulting encryption metadata is stored in Lit's private DynamoDB instance.
  5. A unique ID (generated by Lit) identifying the Wrapped Key is returned.

This process ensures that the private key is securely encrypted and stored, with access tightly controlled via the associated PKP.

Signing Process​

When a signing operation is requested, the following steps occur:

  1. The user provides the unique ID of the Wrapped Key and PKP Session Signatures to the Wrapped Keys SDK.
  2. The SDK retrieves the encryption metadata from the Wrapped Keys backend service.
  3. A specific Wrapped Keys Lit Action is executed, passing the encryption metadata and PKP Session Signatures as parameters.
  4. The Lit Action derives the Ethereum address from the Session Signatures and attempts to decrypt the encryption metadata using the Lit network.
  5. If authorized, the private key is decrypted within a single Lit node's Trusted Execution Environment (TEE).
  6. The decrypted key is used to sign the requested data or transaction.
  7. After signing, the TEE's ephemeral memory is wiped, and the decrypted private key ceases to exist.
  8. The signed data or transaction is returned.
    • There's an option to broadcast signed transactions to a blockchain network to be processed by the network.

This process ensures that the private key is only decrypted and used within the secure confines of the TEE, maintaining a high level of security throughout the signing operation.

Programmability and Key Management​

Wrapped Keys leverage the programmability of Lit Actions, which are JavaScript scripts that define the conditions and logic for key usage. This programmability enables several advanced capabilities such as:

  • Custom Signing Algorithms: Implement signing logic for any blockchain or cryptographic system supported by JavaScript libraries.
  • Flexible Key Usage: Define complex conditions and logic for when and how the Wrapped Key can be used.
  • Integration with External Systems: Interact with APIs, smart contracts, or other external systems as part of the signing process.
  • Dynamic Permission Management: Implement sophisticated, context-aware permission systems for key usage.

Use Cases​

  • Integrating with a wide range of blockchain networks, including those not supported by PKPs
  • Importing existing private keys into the Lit Protocol ecosystem for enhanced security
  • Creating wallet solutions that support diverse cryptographic curves
  • Implementing custom signing algorithms for specialized blockchain projects

Wrapped Keys SDK​

Installing the SDK​

info

The minimum version of the Lit SDK that supports Wrapped Keys is 6.4.0.

npm i @lit-protocol/wrapped-keys

Overview​

For more information on what's offered by the Wrapped Keys SDK, please refer to the following doc pages:

info

The Wrapped Keys SDK methods for:

  • Exporting a Wrapped Key
  • Getting Wrapped Key Metadata
  • Signing an arbitrary message with a Wrapped Key
  • Signing an Ethereum or Solana transaction with a Wrapped Key

expect a Wrapped Key ID as part of their parameters. This ID is generated for each Wrapped Key by the backend service, and is returned by the SDK methods for:

  • Generating a Wrapped Key
  • Importing a private key as a Wrapped Key
  • Storing Wrapped Key Metadata

You can also obtain the IDs for all the Wrapped Keys associated with a specific PKP by using the SDK's listEncryptedKeyMetadata method.