pkns 0.6.0

Public Key Name System Framework

Public Key Name System Framework

This is the Public Key Name System Framework designed as a Public Key Exchange for both centralised and peer-to-peer services. It comes pre-built with useful and powerful CLI tools.

Key Features

• JSON-based Serialization with optional zlib compression for efficient data exchange
• UDP Transport for low-latency, connectionless communication
• Thread Pool Executor for efficient multi-client request handling
• Master Key Vault with network protection for secure key storage
• db86 JSON Database for persistent, queryable data storage
• RSA Cryptography for key generation and digital signatures

Installation

From source

To install from source use the following command, make sure you have setuptools>=50.0.0

python3 seutp.py install

To install from PyPI

pip3 install pkns

Using the PKNS_Table API

The PKNS_Table API is the core for the PKNS Local Services found in the pknscore

from pkns.pknscore import PKNS_Table
new_table = PKNS_Table(PATH_TO_A_TABLE_DIR)

PATH_TO_A_TABLE can be a path to an existing table directory or a new table directory, defaults to ~/.pkns. The API provides all basic table operations and secure master key management.

Master Key Vault

Master keys for peergroups are stored in an encrypted vault within the database and are never exposed over the network:

# Get master key (local-only operation)
master_key = table.get_master_key(fingerprint)

# List all master keys
keys = table.list_master_keys()

# Remove a master key
table.remove_master_key(fingerprint)

Using the PKNS_Server API

The PKNS_Server API is the core of PKNS Network Services found in the pknscore. It provides the correct server handling and configuration for a hosted PKNS Services. The PKNS service runs on the default port 6300 over UDP. It efficiently handles multiple concurrent clients using a configurable thread pool and can be safely daemonized.

from pkns.pknscore import PKNS_Server
server = PKNS_Server(IP_ADDR, PORT, PATH_TO_A_TABLE_DIR, max_workers=10)

IP_ADDR is the IP Address to bind to, defaults to 0.0.0.0, PORT is the port to be used for the server, defaults to 6300, PATH_TO_A_TABLE can be a path to an existing table directory or a new table directory, defaults to ~/.pkns, and max_workers is the number of worker threads in the pool, defaults to 10.

UDP Transport

The server uses UDP for fast, stateless communication:

• Single-packet request/response model for low latency
• Automatic payload signing with SHA256
• JSON serialization with optional zlib compression

Query Syntax

PKNS Query is used for better integration of centralised servers. The query follows a fixed Syntax

pkns://HOST_SERVER[:PORT][/PEERGROUP][/USER]

CLI Tools

CLI Tools help manage the PKNS Tables and Servers easily, they also include useful functions.

Local Table Manager tabman

Managing Local Tables

$ pkns tabman
Usage: pkns tabman [OPTIONS] COMMAND [ARGS]...

  PKNS Table Manager

Options:
  --help  Show this message and exit.

Commands:
  add-peergroup     Add/Create a Peergroup
  add-user          Add Users to a Peergroup
  del-peergroup     Delete/Leave a Peergroup
  del-user          Remove Users from a Peergroup
  get-peergroup     Get Info of a Peergroup
  get-user          Get Users Info from a Peergroup
  rename-peergroup  Rename a Peergroup
  rename-user       Rename a User from a Peergroup

Server Manager server

Server Utilities

$ pkns server
Usage: pkns server [OPTIONS] COMMAND [ARGS]...

  PKNS Server Manager

Options:
  -i, --host TEXT     IP Address to bind  [default: 0.0.0.0]
  -p, --port INTEGER  Port to bind  [default: 6300]
  --help              Show this message and exit.

Commands:
  restart  Restart PKNS Server
  start    Start the PKNS Server
  status   PKNS Server Status
  stop     Stop the PKNS Server

Other utilities

Ping

Ping a Local or Remote Server

$ pkns ping --help
Usage: pkns ping [OPTIONS] [ADDRESS]

  PKNS Ping

Options:
  -n, --nop INTEGER  Number of Pings to send
  --help             Show this message and exit.

Query

Query Local or Remote Server

$ pkns query --help
Usage: pkns query [OPTIONS] QUERY

  PKNS Query

Options:
  --help  Show this message and exit.

Sync

Sync to Local or Remote Server

$ pkns sync --help
Usage: pkns sync [OPTIONS] [ADDRESS]

  PKNS Sync

Options:
  --help  Show this message and exit.

Technical Architecture

Serialization Layer

• JSON-based serialization for structured, human-readable data exchange
• Zlib compression (optional) reduces payload size with PKNSZ prefix for detection
• Type preservation for bytes (base64-encoded) and tuples (preserved through round-trip)
• Replaces legacy pickle5 for better compatibility with db86 JSON storage

Network Layer

• UDP transport (BaseUDPBus) for fast, connectionless communication
• Single-packet request/response model with SHA256 signing
• Thread pool executor on server side for efficient concurrent request handling
• Automatic sender address tracking for reply routing

Storage Layer

• db86 JSON Database for persistent key-value storage
• Automatic schema creation for peergroups and users
• Master Key Vault protected from network access for secure cryptographic key storage
• Per-peergroup user tables for flexible data organization

Security

• Master keys stored only in local vault, never transmitted over network
• Protected tables (vault, peergroups) block unauthorized queries
• SHA256-signed messages prevent tampering
• RSA key generation with configurable sizes (default 3072-bit)