​
Security Architecture

​
AWS Nitro Trusted Execution Environment

Core API leverages AWS Nitro TEE to provide hardware-level security for all cryptographic operations. This ensures that:
  • Private keys are never exposed in plaintext
  • All cryptographic operations happen in an isolated, tamper-proof environment
  • Even Magic cannot access your private keys without proper authorization

​
Key Sharding System

Core API uses advanced cryptographic key sharding to distribute private key material across multiple components, ensuring no single entity has complete access to your wallets.
Diagram showing how private keys are split into 5 shards for security

​
How Key Sharding Works

When a wallet is created, the private key is split using a 2-of-3 threshold scheme:

Shard 1 (Magic)

Always available from Magic’s secure infrastructure. Used for all key operations including recovery.

Shard 2 (Recovery Key)

Returned to your application. Store securely in your database. Used only for wallet recovery when encryption_context is lost.

Shard 3 (Encrypted)

Encrypted with your encryption_context and split into Shards 4 & 5. Required for all non-recovery operations.

Shard 4 (Access Key)

Returned to your application. Store securely in your database. Combined with Shard 5 to recreate Shard 3.

Shard 5 (Magic)

Always available from Magic’s secure infrastructure. Used with Shard 4 to recreate Shard 3.

​
Operation Types

Non-Recovery Operations (Signing transactions, messages)
  • Uses: Shard 1 + Shard 3 (recreated from Shards 4 + 5 + encryption_context)
  • Requires: User’s encryption_context + stored access_key
Recovery Operations (When encryption_context is lost)
  • Uses: Shard 1 + Shard 2
  • Requires: Stored recovery_key
  • Updates: All shard values with new encryption_context

​
Custodial vs Non-Custodial Implementation

Magic does not act as a custodian of your or your users’ digital assets. Ownership and control remain entirely with you and your users. Consult legal professionals about custodial vs non-custodial distinctions in your target markets.
The implementation type depends on how you manage the encryption_context: Non-Custodial Approach:
  • encryption_context is derived from user input (e.g., passphrase, biometric data)
  • User must provide encryption_context for each operation
  • Application cannot perform operations without user consent
Custodial Approach:
  • encryption_context is managed by your application
  • Application can perform operations on behalf of users
  • Requires careful consideration of user consent and regulatory compliance
For non-custodial implementations, consider using user-derived encryption_context such as:
  • User-entered passphrase (hashed)
  • Biometric data
  • Hardware security module (HSM) keys
  • Multi-party computation (MPC) protocols

​
Implementation Patterns

​
Wallet Generation Flow

Flow diagram showing client-server wallet creation process
This flow shows how to securely create a wallet using user-provided encryption_context:
  1. Client: User enters passphrase/biometric data
  2. Client: Hash the user input to create encryption_context
  3. Client: Send encryption_context to your server
  4. Server: Call Core API to create wallet with encryption_context
  5. Server: Store access_key and recovery_key securely
  6. Client: Display wallet address to user
Always hash user input before using it as encryption_context. Never send raw user data to Core API.

​
Non-Recovery Key Operation Flow

Flow diagram showing client-server key signing process
This flow shows how to sign transactions using the user’s encryption_context:
  1. Client: User initiates transaction (e.g., transfer tokens)
  2. Client: User re-enters passphrase/biometric data
  3. Client: Hash the user input to recreate encryption_context
  4. Client: Send transaction + encryption_context to server
  5. Server: Retrieve stored access_key from database
  6. Server: Call Core API to sign transaction
  7. Server: Broadcast signed transaction to blockchain

​
Recovery Flow

Flow diagram showing client-server wallet recovery process
This flow shows how to recover a wallet when the original encryption_context is lost:
  1. Client: User indicates they’ve forgotten their passphrase
  2. Client: User enters new passphrase/biometric data
  3. Client: Hash the new input to create new encryption_context
  4. Client: Send new encryption_context to server
  5. Server: Retrieve stored recovery_key from database
  6. Server: Call Core API recovery endpoint
  7. Server: Update stored keys with new access_key and recovery_key
Recovery operations update all key shards. Ensure you have proper backup procedures before initiating recovery.