☁️
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
  • Sharing Internals
  • Share a file/folder using zboxcli
  • Downloading a shared file/folder
  • Listing files in a shared folder
  • Revoking Access (Public/Private)
  • Private Sharing & Proxy Re-encryption
  1. System
  2. Storage
  3. File Operations

File Sharing

In-depth walkthrough of file sharing feature.

File sharing enables you to share the files in your allocation, either publicly or privately. Check Webapps documentation on how to use it from Blimp/Vult webapps. In this page, we'll be going into the internals of file sharing and the implementation of Proxy Re-Encryption for private file sharing.

Sharing Internals

File sharing depend on an AuthTicket generated for the shared file, that is used to authenticate other users' access to the shared files.

AuthTicket format

type AuthTicket struct {
	ClientID        string `json:"client_id"`
	OwnerID         string `json:"owner_id"`
	AllocationID    string `json:"allocation_id"`
	FilePathHash    string `json:"file_path_hash"`
	ActualFileHash  string `json:"actual_file_hash"`
	FileName        string `json:"file_name"`
	RefType         string `json:"reference_type"`
	Expiration      int64  `json:"expiration"`
	Timestamp       int64  `json:"timestamp"`
	ReEncryptionKey string `json:"re_encryption_key,omitempty"`
	Encrypted       bool   `json:"encrypted"`
	Signature       string `json:"signature"`
}

The AuthTicket is usually encoded in Base64 format and signed with the owner's private key. To access the information contained within the AuthTicket, you can decode it to retrieve the following details:

Parameter
Description

client_id

The client of the user with whom you want to share this file/folder, or empty in case of public sharing.

owner_id

The ID (or wallet address) of the owner of the allocation.

allocation_id

The ID of the allocation containing this file.

file_path_hash

Hash of the file/folder path.

actual_file_hash

file_name

The name of the shared file/folder.

reference_type

Indicates whether it is a file or a folder.

expiration

The duration for which the AuthTicket remains valid.

timestamp

The timestamp when the AuthTicket was created.

re_encryption_key

encrypted

signature

The signature of the AuthTicket, used for validation.

Share a file/folder using zboxcli

You can share a file using the share command in zboxcli:

./zbox share --allocation <allocation-id> --remotepath <path-of-the-file-or-folder-on-the-allocation> [other flags] 
Auth token eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3ZTExOTQwNmQ4ODg3ZDAyOGIxNDE0YWNmZTQ3ZTg4MDhmNWIzZjk4Njk2OTk4Nzg3YTIwNTVhN2VkYjk3YWYiLCJhbGxvY2F0aW9uX2lkIjoiODlkYjBjZDI5NjE4NWRkOTg2YmEzY2I0ZDBlODE0OTE3NmUxNmIyZGIyMWEwZTVjMDZlMTBmZjBiM2YxNGE3NyIsImZpbGVfcGF0aF9oYXNoIjoiM2NhNzIyNTQwZTY1M2Y3NTQ1NjI5ZjBkYzE5ZGY2ODk5ZTI0MDRjNDI4ZDRiMWZlMmM0NjI3ZGQ3MWY3ZmQ2NCIsImFjdHVhbF9maWxlX2hhc2giOiIyYmM5NWE5Zjg0NDlkZDEyNjFmNmJkNTg3ZjY3ZTA2OWUxMWFhMGJiIiwiZmlsZV9uYW1lIjoidGVzdC5wZGYiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpcmF0aW9uIjoxNjM1ODQ5MzczLCJ0aW1lc3RhbXAiOjE2MjgwNzMzNzMsInJlX2VuY3J5cHRpb25fa2V5IjoiIiwiZW5jcnlwdGVkIjpmYWxzZSwic2lnbmF0dXJlIjoiZDRiOTM4ZTE0MDk0ZmZkOGFiMDcwOWFmN2QyMDAyZTdlMGFmNmU3MWJlNGFmMmRjNmUxMGYxZWJmZTUwOTMxOSJ9

What happens in the background is simply :

  • The blobber creates/updates the ShareInfo for the file_path_hash in the AuthTicket, after validating the request.

shareInfo := reference.ShareInfo{
	OwnerID:                   authTicket.OwnerID,
	ClientID:                  authTicket.ClientID,
	FilePathHash:              authTicket.FilePathHash,
	ReEncryptionKey:           authTicket.ReEncryptionKey,
	ClientEncryptionPublicKey: encryptionPublicKey,
	ExpiryAt:                  common.ToTime(authTicket.Expiration).UTC(),
	AvailableAt:               common.ToTime(availableAt).UTC(),
}

Downloading a shared file/folder

./zbox download --authticket <the-generated-AuthTicket> --localpath <local-path-to-save-the-file>

What happens in the background is simply:

  • The blobber does some validation and verification checks on the request to make sure all is lined up, including:

    • Checks the path in the request is actually inside the allocation in the request.

    • Verifies the signature of the AuthTicket.

    • Verifies the owner of the ticket is the same as the owner of the allocation.

    • If the ticket has ClientID (meaning the file is privately shared with this specific client), then the blobber will verify that this client actually has access to this blobber. Otherwise, if ClientID is empty, then the file is publicly shared.

    • Checks the time now is later than availableAfter from ShareInfo above.

    • Checks the expiry, if expiration date is provided. Otherwise, a default expiry date of 90 Days used.

    • Checks the time now is later than availableAfter from ShareInfo stored for this ticket.

Listing files in a shared folder

To list the files listed under the shared path in the AuthTicket, you can use the list command from zboxcli:

./zbox list --authticket $AUTH_TICKET

What happens under the hood is simply:

listReq := &ListRequest{Consensus: Consensus{RWMutex: &sync.RWMutex{}}}
listReq.allocationID = a.ID
listReq.allocationTx = a.Tx
listReq.blobbers = a.Blobbers
listReq.fullconsensus = a.fullconsensus
listReq.consensusThresh = a.consensusThreshold
listReq.ctx = a.ctx
listReq.remotefilepathhash = lookupHash
listReq.authToken = at
// It later adds "offset" and "limit" for the request for pagination.
  • The client collects replies from the blobbers and returns the result in case consensus is achieved.

Revoking Access (Public/Private)

To revoke access for a publicly shared file, you'll need to use the zbox share endpoint with --revokeflag:

./zbox share --allocation <allocation-id> --revoke --remotepath <remote-path-of-the-shared-file> --clientid <client-id> 

What happens under the hood is simply:

  • The blobber deletes the token related to the mentioned file (and the mentioned client in case of private sharing).

Private Sharing & Proxy Re-encryption

Our storage system enables secure private file sharing through authorization tickets (auth tickets) while maintaining access control and data confidentiality.

When a user shares a file privately, they generate an auth ticket tied to a specific recipient (client ID). This ensures that only the intended user can access the shared file without exposing the data to unauthorized parties.

For encrypted files, the system utilizes a proxy re-encryption (PRE) scheme that allows file sharing without requiring the owner to download and manually re-encrypt the data. This ensures a secure and efficient sharing process while maintaining end-to-end encryption.

1. Referee Key Generation

Before a file is shared, the recipient, referred to as the referee, generates an encryption key pair.

  • The key pair consists of a private key and a public encryption key.

  • The public encryption key is derived from the referee's private key, ensuring that only the referee can decrypt the final re-encrypted file.

2. Re-Encryption Key Computation

To enable proxy re-encryption, the file owner generates a re-encryption key using the following inputs:

  • Their private key.

  • The public encryption key of the referee.

  • The original encryption key of the file, which is unique for every encrypted file.

This computed re-encryption key is included in the auth ticket and stored on the blobbers responsible for holding the file.

3. Proxy Re-Encryption by Blobbers

When the referee initiates the file download, the blobbers apply the re-encryption key to transform the encrypted file.

  • The blobbers perform the re-encryption process without decrypting the file.

  • The transformed file remains encrypted and is accessible only to the referee.

  • Since the blobbers never gain access to the decrypted data, end-to-end encryption is preserved.

4. Decryption by the Referee

Once the re-encrypted file is retrieved, the referee decrypts it using their private key.

  • The private key used for decryption corresponds to the public encryption key that was provided for re-encryption.

  • The referee can seamlessly access the shared file without requiring any additional steps from the file owner.

Proxy re-encryption ensures that file sharing remains both secure and efficient without compromising data confidentiality.

  • The file owner does not need to manually re-encrypt the data before sharing it with different users.

  • Data remains encrypted throughout the entire process, ensuring security even during re-encryption.

  • Blobbers facilitate the re-encryption process without having access to the actual file contents.

  • Only the intended recipient can decrypt and access the file, preventing unauthorized access.

Always keep your private keys safe and secure.

PreviousDownloadNextPartial Error Recovery

Last updated 1 month ago

The actual hash of the contents of the shared file, which is used in the , or just empty in case of folder.

This is the Re-Encryption key used in case of private sharing. Discussed below in .

Indicates whether the file should be encrypted by the recipient public key on retrieval. Discussed below in .

Check the for full usage docs of this command. After running the command you'll get an AuthTicket (encrypted in Base64), which you can share with whomever you want to access this file.

The client (in this case zboxcli via ) creates the AuthTicket and signs it with the private key of the owner.

The client submits the ticket in a ShareRequest to one of the blobber of the allocation, via the endpoint: POST /v1/marketplace/shareinfo/ (see in documentation).

To download a shared file, you can utilize the download command from , using the authTicket that was provided in the share step:

Check the for full usage docs of this command.

In case of folder download, you'll need to download the files inside the folder one by one, by providing either remotepath or lookuphash flags to the download command.lookuphash is the hash of file path and allocation ID, concatenated, using the function of encryption package in GoSDK.

The client (in this case zboxcli, via ) prepares the request based on the given flags. For example, it creates a lookuphash if the remotepath is given, because lookuphash is required for the download request of the blobber API.

The client sends the blobber a series of downloadRequest's, block-by-block, on the endpoint: /v1/file/download/ (see ), attaching the AuthTicket in that response.

Checks user has enough daily download quota (see ).

Checks the lookuphash provided in the request is the same as the file_path_hash in the AuthTicket, otherwise (in case of directory tickets) checks if the provided lookuphash translates to a (representation of the file in the database) whose path starts with the file_hash_pathin the ticket (i.e. the requested file lies inside the directory for which the ticket is issued).

Check the ticket is not revoked (see ).

Check the for full usage docs of this command.

The client (in this case zboxcli, via ) build a ListRequest with the AuthTicket and the file_path_hash.

The client then sends the list request to the allocation blobbers, seeking a consensus based on the returned results. The blobber API endpoint used is: /v1/file/list/(see )

The blobber will then verify the AuthTicket (same as in ) and prepare the list of descendant files/directories of the required path, based on the given parameters.

Check the for full usage docs of this command.

The client (in this case zboxcli, via ) sends revoke share request to all the blobbers of the allocation. The blobber API endpoint used is: DELETE /v1/marketplace/shareinfo/{allocation} (see ).

zboxcli repo README
Zboxcore SDK
zboxcli
zboxcli repo README
Hash
Zboxcore SDK
Download
ReferenceObject
zboxcli repo README
Zboxcore SDK
zboxcli repo README
Revoking
Download
file system
Private Sharing
Private Sharing
Zboxcore SDK
Blobber API
Blobber API
Blobber API
Blobber API