Key Server Architecture

The Tricryption Key Server (kS) is a layered, pooled, multi-protocol server sitting over the key database (KDB). It accepts connections from agents and from Remote Engines (rE), authenticates the caller, and serves key operations under access control. This page describes that server in terms of roles and responsibilities, not internal class names.

Architectural layers

The kS is organized into five layers. The lower layers carry the request path from connection intake down to the database; the Base layer is cross-cutting infrastructure used by every other layer, not only the one above it:

Layer	Responsibility
Listener	Listens for and accepts incoming client / rE connections.
Container	The runtime: connection management, the worker pool, and configuration.
Core	Key store, key services, the cryptographic provider, authentication, and authorization.
Persistency	Object-relational mapping, and database adapters that read and write the KDB.
Base	Foundational utilities: memory management, configuration, serialization, and error handling.

Request lifecycle

A key operation flows in through the connection layers and back out:

1. Accept. A listener accepts an incoming connection.
2. Assign a worker. A connection manager takes a worker from the worker-thread pool to service the connection — work is never run on the listener itself.
3. Select the protocol. The connection's protocol is selected (authenticated or certificate-based).
4. Authenticate. The authentication service establishes the calling principal — who the caller is.
5. Authorize. A separate authorization step runs the access check (RBAC / DAC) — what that principal may do.
6. Dispatch to Core. The request is dispatched to a Core operation — key store, encrypt / decrypt, or object management.
7. Return. The result travels back out through the same connection, and the worker is returned to the pool.

Connection handling and pooling

The Container layer is built for concurrency through pooling:

• Listeners accept connections; multiple may be configured.
• Connection managers track active connections and hand them to workers.
• A worker-thread pool services requests, sized by an initial and a maximum pool size so the server scales under load without unbounded thread growth.
• Configuration sets the tunables — pool sizes, listener endpoints, database pool sizes, and log destination — read at startup.

The same pooling discipline extends to the database: the Persistency layer holds a database connection pool rather than opening a connection per request.

Protocols and authentication

The kS speaks two connection protocols, selected per connection:

• an authenticated protocol that establishes a principal, and
• a certificate-based protocol for X.509 / TLS client-certificate authentication.

Transport is secured with TLS 1.3 (server-pinned minimum), using the two AES-GCM cipher suites — TLS_AES_256_GCM_SHA384 and TLS_AES_128_GCM_SHA256; ChaCha20-Poly1305 is excluded. Authentication resolves the caller to a principal. Each authenticated principal type pairs a credential with its protocol:

• Password (SRP)
• Certificate (X.509)
• LDAP (Kerberos) — build-dependent; Password (SRP) and Certificate (X.509) are the self-authenticating types every kS provides.

A further principal type, Group, is a collection principal: it is not authenticated by a credential or protocol, but is used as a grant target for discretionary access control (DAC) — rights granted to a group are inherited by its members (see Key Management Process).

Authentication establishes who the caller is; authorization is a separate step that decides what they may do.

Core services

The Core layer is where key work happens:

• Key store — generates new keys and fetches existing ones by their hidden link. This is the entry point for the encrypt / decrypt flows described in Key Management Process.
• Key services — the encrypt and decrypt primitives over a resolved key, plus object management.
• Cryptographic provider — an abstraction over the cryptographic backend. The shipping backend is OpenSSL 3.0; the default data algorithm is AES-256 (AES-192 / AES-128 selectable). The abstraction also accommodates an HSM acting as the cryptographic module (see Key Hierarchy and Bootstrapping).
• Authentication — establishes the calling principal from the connection's credentials.
• Authorization — a separate access check (RBAC / DAC) that evaluates the per-key ACL against the authenticated principal before any key is released. SDK surface: TEACLInfo and TEACLEntry.

Persistency

The Persistency layer isolates the rest of the server from the database. A database-adapter abstraction presents a uniform load / save / remove / query interface to the Core, while the concrete adapter targets the deployed database. The KDB is multi-vendor — the adapter layer is what makes that possible — and the schema is described logically in Key DB Structure. Connections are pooled, as noted above.

Clustering and trust

Multiple kS instances can run together, and a kS can trust another:

• Instance namespacing. Every object is identified by a 64-bit object ID that is instance-namespaced, so independently running kS instances generate identifiers that never collide. This is the foundation of clustering.
• Cross-kS trust. A kS records the other servers it trusts (their identity, host, and port) and maps local principals to those trusted servers, enabling cross-server key exchange. SDK surface: TETrustedServerInfo and TEPrincipalTrustMatrix. The certificate keys that anchor this trust are part of the Master Key inventory.

Remote Engine and agent connectivity

Two kinds of client connect to the kS:

• Agents — embedded via the SDK (SDK Reference) — request keys and perform encryption locally on behalf of an application.
• Remote Engines (rE) — standalone engines that perform encryption close to the data, fed Session Keys and T-tags by the kS over secured transport. An rE protects itself with a key obtained from the kS; see Key Hierarchy and Bootstrapping.

In both cases the kS remains the single point that generates, stores, and access-controls keys; the ciphertext is produced at the client side.

The rE local store and offline operation

The rE keeps a small local store — a SQLite database on the rE host — for the state it needs when it cannot reach the kS. Its principal content is the Hidden-Link Status record: the per-link / T-tag status (for example, marking a link offline) that supports the rE's OFFLINE mode. The surface for reading and setting these records is TEAdminLocal — see the T-tag status and go-offline samples.

Field	Logical type	Role
Hidden link	link	The link whose status this is
Principal	identifier	Associated principal
System	identifier	Owning system
Token	identifier	Status token
Status	flag	Current status
Signature	signature	Per-record HMAC

This store belongs to the rE, not to the kS's key database — the KDB entity model deliberately excludes it.

Related pages

• Key Management Process — the flows this server executes.
• Key Hierarchy and Bootstrapping — the key levels and the boot sequence that brings the server online.
• Key DB Structure — the database this server persists to.