# 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. {% hint style="info" %} 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. {% endhint %} ### 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. {% hint style="info" %} TTL is always set to 0 (infinite) as of now, but will be implemented in the future. {% endhint %} **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. **S**igning 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:

Fig1: KMS 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: ## Deletes existing master key. > Deletes existing master key, propagating changes to Zauth. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/delete/:client_id":{"post":{"description":"Deletes existing master key, propagating changes to Zauth.","summary":"Deletes existing master key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Generate new split key. > Generates new split key using previously stored or generated master key, propagating changes to zauth. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/key/:client_id":{"post":{"description":"Generates new split key using previously stored or generated master key, propagating changes to zauth.","summary":"Generate new split key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## GET /keys/:client\_id > Retrieves split keys for the given master key. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/keys/:client_id":{"get":{"summary":"Retrieves split keys for the given master key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## GET /restrictions > Retrieves restrictions for the given split key. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/restrictions":{"get":{"summary":"Retrieves restrictions for the given split key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true},{"type":"string","description":"Peer public key of the split key, which restrictions should be updated","name":"X-Peer-Public-Key","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Update restrictions for the existing split key. > Updates restrictions for existing split key, propagating changes to Zauth. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/restrictions/:client_id":{"put":{"description":"Updates restrictions for existing split key, propagating changes to Zauth.","summary":"Update restrictions for the existing split key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true},{"type":"string","description":"Peer public key of the split key, which restrictions should be updated","name":"X-Peer-Public-Key","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Revoke existing split key. > Revokes existing split key, propagating changes to Zauth. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/revoke/:client_id":{"post":{"description":"Revokes existing split key, propagating changes to Zauth.","summary":"Revoke existing split key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"string"}}},"description":"Public key of split key to be removed","required":true}}}}} ``` ## Share existing split key to the givens user. > Shares previously created split key to the given user. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/share":{"post":{"description":"Shares previously created split key to the given user.","summary":"Share existing split key to the givens user.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Store 0box wallet private key. > Stores external 0box generated wallet private key as master key used to generate new split keys. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/store":{"post":{"description":"Stores external 0box generated wallet private key as master key used to generate new split keys.","summary":"Store 0box wallet private key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Generate new wallet. > Generates new wallet used as master key to generate new split keys. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/wallet":{"post":{"description":"Generates new wallet used as master key to generate new split keys.","summary":"Generate new wallet.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## GET /wallets > Retrieves split wallets for the given master key. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/wallets":{"get":{"summary":"Retrieves split wallets for the given master key.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ``` ## GET /wallets/shared > Retrieves shared split keys shared with the given user. ```json {"openapi":"3.1.1","info":{"version":"0.0.1"},"paths":{"/wallets/shared":{"get":{"summary":"Retrieves shared split keys shared with the given user.","parameters":[{"type":"string","description":"0box generated JWT token","name":"X-Jwt-Token","in":"header","required":true}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}}} ```