Privicore
  1. Public key
Privicore
  • Privicore API
  • Utility
    • Utility
    • Check server health
      GET
    • Request command id status
      GET
  • Profile
    • Profile Model and Authentication Workflow
    • Register new profile
      POST
    • Authenticate
      POST
    • Retrieve profile id
      GET
    • Change password
      POST
    • Generate qr token for authorization
      POST
    • Reauthorize authorization token
      POST
    • Revoke authorization token
      POST
    • Retrieve token expiry
      POST
  • OAuth Application
    • OAuth Application Management
    • Register OAuth Application
      POST
    • Retrieve OAuth app configuration
      POST
    • Request OAuth app authorization code
      GET
    • Retrieve OAuth app authorization code
      POST
    • Obtain OAuth app access token
      POST
    • OAuth application list
      GET
    • Retrieve OAuth application scope
      GET
    • Refresh OAuth app access token
      POST
  • Public key
    • Public and Private Key Management
    • Generate your private and public keys
      GET
    • Register public key
      POST
    • Retrieve public key
      GET
    • Retrieve CAB public key
      GET
  • Data Token
    • Data Token Management
    • Reserve token space
    • Retrieve temporary data token
    • Exchange data for token
    • Upstream file via stream auth
    • Request data via token
    • Download data
    • Configure information security risk meta
    • Configure file meta
    • List data tokens
    • Update data token
    • Delete data
    • Get data token transaction count statistics.
  • Device
    • Request unique identifier (i.e. Register new device)
    • Retrieve unique identifier
    • Retrieve profile devices
    • Configure device meta
    • Approve device
    • Reject device
    • Retrieve device configuration
    • Remove device
  • Storage
    • Register storage device
    • List storage devices
    • Synchronize device
    • Remove storage
  • Verified authenticator
    • Register authenticator
    • List verified authenticators
    • Retrieve voting strategy
    • Set quorum size
    • Set quorum strategy
    • Set voting time limit
    • Set maximum voting attempts
    • Remove authenticator
    • Register voting configuration
    • Update voting configuration
    • List voting configurations
    • Retrieve voting configuration
  • Policy
    • List policy templates
    • Register policy
    • List active policies
    • List inactive policies
    • Activate policy
    • Deactivate policy
    • Delete policy
    • List registered policies
    • Retrieve registered policy
  • Directory
    • Register Directory
    • Retrieve owned Directories
    • Retrieve assigned directories
    • Retrieve Directory
    • Create Directory User
    • Update user information
    • Invite Profile
    • Set profile password
    • List Directory Invites
    • Process Invitation
    • Retrieve directory profile
    • List directory users
    • Directory profiles info
    • Create profile device
    • Add storage device to profile
    • List directory devices
    • Create directory voting pool
    • Store directory meta information
  • Voting
    • Create voting
    • Check pool status
  • Schemas
    • Response
      • CommandAccepted
      • Unauthorized
      • ValidationErrors
    • Schemas
    • profileId
    • deviceIdentifier
    • directoryId
    • directoryName
    • directoryShortName
    • givenName
    • familyName
    • createdAt
    • meta
  1. Public key

Public and Private Key Management

Introduction#

Public and private key cryptography forms the foundation of secure communication and authentication within the system. These cryptographic keys serve two critical purposes:
Data Encryption: End users encrypt sensitive data using keys before storage or transmission
Identity Verification: The system verifies that requests originate from valid, authenticated users

How Key-Based Authentication Works#

Key Pair Generation#

Each profile must generate a cryptographic key pair consisting of:
Private Key: A secret key kept exclusively by the profile owner, used for signing requests and decrypting data
Public Key: A shareable key registered with the system, used for verifying signatures and encrypting data

Key Generation Implementation#

The system uses Curve25519 elliptic curve cryptography for key generation. Keys are generated using the TweetNaCl library, which provides secure, audited implementations of the NaCl cryptographic primitives.
JavaScript Example:

Valid Key Format#

A valid public key for registration must be:
Signed: The raw 32-byte Curve25519 public key must be prefixed with a 4-byte version tag (0x31420500)
Hashed: A BLAKE2b-512 hash of the versioned key is appended for integrity verification
Encoded: The final binary data is hex-encoded for transmission
Structure:
[4 bytes: version tag][32 bytes: public key][64 bytes: BLAKE2b hash]
Total: 100 bytes (200 hex characters)

Deterministic Key Generation#

For automated systems or deterministic key derivation, you can generate keys from a seed:

Public Key Registration Requirement#

As mentioned in the Profile Management section, public key registration is mandatory for profile activation. Until a signed public key is successfully registered, the profile cannot participate in authenticated workflows or access system resources.

Signature Verification#

When a profile makes requests to the system, it signs those requests using its private key. The system uses the registered public key to verify the signature, ensuring:
Authenticity: The request actually came from the claimed profile
Integrity: The request was not modified in transit
Non-repudiation: The profile cannot deny making the request

Key Management Operations#

The system provides endpoints for complete key lifecycle management:
Generate Keys: Create a new cryptographic key pair
Register Public Key: Submit your signed public key to activate your profile
Retrieve Public Key: Fetch your registered public key
Retrieve CAB Public Key: Obtain the system's Certificate Authority Bundle (CAB) public key for verifying system-signed responses

Security Best Practices#

Never share your private key with anyone or any service
Store your private key securely using appropriate key management tools
The private key is 32 bytes - keep it as binary or securely encoded

Key Usage Flow#

Profile → Generate Key Pair (Curve25519)
              ↓
Create Signed Public Key (Version + Key + Hash)
              ↓
Register Public Key → Profile Activated
              ↓
Sign Requests with Private Key
              ↓
System Verifies with Public Key
              ↓
Request Authenticated → Access Granted

CAB Public Key#

The Certificate Authority Bundle (CAB) public key is the system's own public key, used to verify responses and data signed by the system. This ensures that responses you receive genuinely originate from the system and have not been tampered with.
Modified at 2025-12-09 10:53:31
Previous
Refresh OAuth app access token
Next
Generate your private and public keys
Built with