☁️
Zus Docs
  • About Züs
  • System
    • Providers and Services
      • Miner
      • Sharder
      • Blobber
      • Validator
      • Authorizer
      • Node Locator (0DNS)
    • Storage
      • Architecture and Data Management
      • Protocol
        • Allocations
        • Reference Objects
        • Challenges
        • Write Markers
          • Chain Hashing
          • Two Commit
        • Blobber Repair Protocol
      • ZS3 Server
        • Backup, Recovery and Replication
        • Encryption and Compression
        • S3FS Setup and Usage
        • Backup & Recovery with Restic on Blimp + ZS3 Server
        • Backup & Recovery with Veeam on Blimp + ZS3 Server
      • File Operations
        • Upload
        • Download
        • File Sharing
        • Partial Error Recovery
        • Streaming
        • Rent a Blobber
    • Smart Contracts
      • Storage S.C.
      • Miner S.C.
      • ZCN S.C.
      • ERC-20 S.C.s
      • Bridge Protocol
    • Blockchain & Consensus
      • Entities
    • User Authentication and Wallet Management System
      • OKTA Integration
      • Key Management System (KMS)
  • APIs
    • 0DNS API
    • JS API
    • Mobile API
  • CLIs
    • Storage CLI
      • Quickstart
      • Configuring the tool
    • Wallet CLI
      • Wallet Configuration
      • Quickstart
      • Configuring the tool
  • SDKs
    • Go SDK
      • GO SDK Microservices
    • JS SDK
  • Tokenomics
    • Staking
    • Reward & Penalty
  • ✨Züs Apps
    • 🗝️Vult
      • Getting Started
        • Web
        • Mobile
      • Vult AI
        • Batch Processing
        • Memory Retention
        • Technical Implementation
        • Architecture Overview
      • Login / Register
      • File Management Pages
      • File Sharing
      • Storage Management Dashboard
      • Storage Maintenance and Troubleshooting
      • Züs Subscription
      • Wallet Management
      • Refer a friend
      • Settings
    • 🏗️Blimp
      • Getting Started
      • Login / Register
      • Configure Storage
        • Create Standard Storage Allocation
        • Create Enterprise Allocation
        • Create S3 Server Allocation
        • Create Cloud Migration Allocation
        • Allocation Maintenance and Troubleshooting
      • File Management Pages
      • File Sharing
      • Manage Allocations
      • Upgrade Storage
      • Blimp Vault
      • Refer a friend
      • Settings
      • Launching ZS3 Server
      • Using CLI to backup files into Blimp + ZS3 Server
    • 🏠Chimney
      • Getting Started
      • Login / Register
      • Create New Deployment
      • Manage Your Deployments
      • Homepage
      • Staking Dashboard
      • Rank Dashboard
      • Monitor Dashboard
      • Stats Dashboard
      • Logs Dashboard
      • Wallet Dashboard
      • Operations on your Deployments
      • Restricted Blobbers
      • Settings
        • Manage Profile
        • Wallet Settings
        • Update Blobber Settings
        • Update Blobber Version
        • Refer a friend
        • Help
    • 🌐Atlus
      • Getting Started
      • Home page
      • Service Providers Page
      • Charts Page
        • Market Charts
        • Network Charts
        • Storage Charts
      • Blockchain Page
      • Server Map Page
      • Storage Explainer Page
      • Details Pages
        • Block Details Page
        • Transaction Details Page
        • Wallet Details Page
        • Miner Details Page
        • Sharder Details Page
        • Blobber Details Page
        • Validator Details Page
        • Authorizer Details Page
        • Allocation Details Page
      • Appendix: Common Components
    • ⚡Bolt
      • Getting Started
        • Web
        • Mobile
      • Login / Register
      • Sign In with external wallet
      • Staking Dashboard
      • Staking/Unstaking a provider
      • Claiming Rewards
      • Send/Receive ZCN tokens
      • Buy ZCN
      • Deposit/Withdraw ZCN tokens
      • Activity Dashboard
      • Refer a friend
      • Settings
  • Releases
    • Hardfork
Powered by GitBook
On this page
  1. System
  2. User Authentication and Wallet Management System

Key Management System (KMS)

The Key Management System (KMS) in the 0Chain network enhances security by introducing split key mechanisms for transactions and messages.

This ensures that signature-based authentication is performed securely using a dual-key approach, reducing the risk of key compromise.

  • Standard Signature Mode: In the traditional signature mechanism, a single key pair is used:

    • The private key generates the signature.

    • The public key (client key) verifies the signature.

  • KMS Mode: In KMS mode, two key pairs are used to generate a signature:

    • The first key pair is used by the user to create an initial signature.

    • The second key pair is securely managed within the 0Chain infrastructure and is inaccessible to the end user.

    • The final signature is formed by combining both signatures, which is then verified using the user's public key.

This approach ensures enhanced security and enables the concept of split keys, allowing controlled access and revocation without exposing the master private key.

This approach is used in provider renting logic. With its help 0chain operational wallet is not exposed to the user and user can use its split key instead. When renting period ends, that split key is revoked.

KMS Components: ZVault and ZAuth

KMS operations rely on two essential services: ZVault and ZAuth.

ZVault

ZVault acts as a secure key storage and management system. It is responsible for:

  • Holding both master and split keys for user wallets.

  • Generating split keys based on the user’s master private key.

  • Managing permissions and revocation of split keys.

  • Ensuring secure storage using Enclave hardware encryption, which provides an additional layer of protection against unauthorized access.

Key Request Process

  1. The user initiates a key request using a JWT (JSON Web Token) for enterprise authentication.

  2. The request is sent to ZVault, which validates the request and determines whether to grant access to the key shards.

  3. ZVault retrieves the necessary key shard and assigns it a TTL (Time-To-Live) to ensure temporary access.

TTL is always set to 0 (infinite) as of now, but will be implemented in the future.

Security Considerations

  • Enterprise-level authentication with JWT ensures only authorized systems or users can request keys.

  • Encryption in transit and at rest ensures that the key shard remains secure.

ZAuth

ZAuth is responsible for signature generation and combination.

It ensures that transactions are authorized using the KMS approach while maintaining compliance with access control policies.

Signing Process

  1. A sign request is generated, typically for a transaction or message verification initiated by the user.

  2. ZAuth receives the key shard, along with the TTL (Time-To-Live) and authentication details.

  3. ZAuth verifies the requestor’s permissions using the authentication metadata to ensure that the operation is authorized.

  4. If the request is valid, ZAuth proceeds to generate a second signature using infrastructure-managed keys, which are securely stored.

  5. ZAuth then combines the user-generated signature (created with their private key) and the infrastructure-generated signature into a final verifiable signature.

  6. The final signature is returned to the requestor, enabling them to use it for transaction execution or message validation.

Security Considerations

  • ZAuth does not expose private keys, ensuring that signing operations occur in a secure enclave.

  • Multi-signature validation ensures that all requests go through a proper verification process.

  • Audit logs and tracking mechanisms allow for monitoring and forensic analysis in case of security incidents.

Workflow Diagram

The image below illustrates the interaction between ZVault and ZAuth in the key management and signing process:

  1. User initiates a key request. The request includes a JWT (JSON Web Token) for enterprise authentication. This request is sent to ZVault for key management.

  2. ZVault generates a split key. ZVault holds the user's master private key. It generates split keys based on the user’s master private key. These split keys allow wallet sharing with limited permissions.

  3. User signs the request with their split key. The first signature is created on the user side using the split key. This signature confirms the identity of the user.

  4. Request is sent to ZAuth for the second signature. ZAuth generates a second signature using a hidden infrastructure key. This key is not available to the end user, ensuring secure transaction handling.

  5. Signatures are combined. ZAuth merges the user’s signature with the infrastructure signature. This combined signature is then verified by the user’s public client key.

  6. Final request Auth Header is forwarded.

This architecture ensures a secure, permission-controlled, and revocable key signing process while preventing full key exposure at any step.

Benefits of KMS Mode

  • Enhanced security: User wallets operate with split keys, preventing unauthorized access and minimizing exposure to attacks.

  • Wallet sharing with limited permissions: Specific operations can be delegated to users without full wallet access, enabling controlled access management.

  • Revocation of split keys: Shared keys can be revoked when needed, ensuring controlled access to wallet functions.

  • Minimized risk in provider renting logic: Enables safe interaction with 0Chain operational wallets while ensuring the user’s transactions remain secure and independent.

  • Secure multi-party access: Ensures multiple users can interact with the same wallet while maintaining distinct access permissions.

API Documentation

For API details, check below api documentation:

PreviousOKTA IntegrationNextAPIs

Last updated 15 days ago

Fig1: KMS Process

Deletes existing master key.

post

Deletes existing master key, propagating changes to Zauth.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
200
OK
400
Bad Request
500
Internal Server Error
post
POST /delete/:client_id HTTP/1.1
Host: 
Accept: */*

No content

Generate new split key.

post

Generates new split key using previously stored or generated master key, propagating changes to zauth.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
201
Created
400
Bad Request
500
Internal Server Error
post
POST /key/:client_id HTTP/1.1
Host: 
Accept: */*

No content

Retrieves split keys for the given master key.

get
Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
200
OK
400
Bad Request
500
Internal Server Error
get
GET /keys/:client_id HTTP/1.1
Host: 
Accept: */*

No content

Retrieves restrictions for the given split key.

get
Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

X-Peer-Public-KeyanyRequired

Peer public key of the split key, which restrictions should be updated

Responses
200
OK
400
Bad Request
500
Internal Server Error
get
GET /restrictions HTTP/1.1
Host: 
Accept: */*

No content

Update restrictions for the existing split key.

put

Updates restrictions for existing split key, propagating changes to Zauth.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

X-Peer-Public-KeyanyRequired

Peer public key of the split key, which restrictions should be updated

Responses
200
OK
400
Bad Request
500
Internal Server Error
put
PUT /restrictions/:client_id HTTP/1.1
Host: 
Accept: */*

No content

Share existing split key to the givens user.

post

Shares previously created split key to the given user.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
200
OK
400
Bad Request
500
Internal Server Error
post
POST /share HTTP/1.1
Host: 
Accept: */*

No content

Store 0box wallet private key.

post

Stores external 0box generated wallet private key as master key used to generate new split keys.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
201
Created
400
Bad Request
500
Internal Server Error
post
POST /store HTTP/1.1
Host: 
Accept: */*

No content

Generate new wallet.

post

Generates new wallet used as master key to generate new split keys.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
201
Created
400
Bad Request
500
Internal Server Error
post
POST /wallet HTTP/1.1
Host: 
Accept: */*

No content

Retrieves split wallets for the given master key.

get
Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
200
OK
400
Bad Request
500
Internal Server Error
get
GET /wallets HTTP/1.1
Host: 
Accept: */*

No content

Retrieves shared split keys shared with the given user.

get
Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Responses
200
OK
400
Bad Request
500
Internal Server Error
get
GET /wallets/shared HTTP/1.1
Host: 
Accept: */*

No content

  • KMS Components: ZVault and ZAuth
  • Workflow Diagram
  • Benefits of KMS Mode
  • API Documentation
  • POSTDeletes existing master key.
  • POSTGenerate new split key.
  • GETRetrieves split keys for the given master key.
  • GETRetrieves restrictions for the given split key.
  • PUTUpdate restrictions for the existing split key.
  • POSTRevoke existing split key.
  • POSTShare existing split key to the givens user.
  • POSTStore 0box wallet private key.
  • POSTGenerate new wallet.
  • GETRetrieves split wallets for the given master key.
  • GETRetrieves shared split keys shared with the given user.

Revoke existing split key.

post

Revokes existing split key, propagating changes to Zauth.

Header parameters
X-Jwt-TokenanyRequired

0box generated JWT token

Body
stringOptional
Responses
200
OK
400
Bad Request
500
Internal Server Error
post
POST /revoke/:client_id HTTP/1.1
Host: 
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 6

"'text'"

No content