Key DB Structure
The key database (KDB) is where the Tricryption Key Server (kS) persists everything it manages: the wrapped Session and System Keys, the access-control lists that govern them, the principals it authenticates, the cross-server trust relationships, and the audit trail. This page describes the KDB as a logical entity-relationship model — what is stored and how the pieces relate — independent of any particular database product or physical layout.
Entities below are described with logical field types only — identifier, string, encrypted-blob, link, counter, timestamp, flag, and signature. Column widths, physical types, and vendor specifics are deliberately out of scope. The kS persists the KDB through a database-adapter layer and supports multiple database back-ends; the model here is the durable shape common to all of them.
Two facts hold across the whole model:
- Object identifiers are 64-bit. Every object, principal, ACL, and key counter is identified by a 64-bit object ID. Identifiers are instance-namespaced so that multiple kS instances can run as a cluster without colliding.
- Master Keys are not in the KDB. The KDB holds encrypted System Keys, encrypted Session Keys, ACLs, principals, trust, and audit records — but the Master Keys live in the protector-secured Master Key Container, off-database (see Key Hierarchy and Bootstrapping).
Core key entities
System Key
The wrapped System Keys that protect Session Keys. See Key Hierarchy and Bootstrapping.
| Field | Logical type | Role |
|---|---|---|
| System Key ID | identifier | Unique; the value a T-tag references |
| Key blob | encrypted-blob | The System Key, wrapped by a Master Key |
| System ID | identifier | Owning Tricryption system / instance |
| Object ID | identifier | Primary identity |
| Created / Expired | timestamps | Lifecycle |
| Signature | signature | Per-record HMAC |
Session Key
The wrapped per-element data keys. The SDK key surface is TEKey.
| Field | Logical type | Role |
|---|---|---|
| Key link | link (identifier) | Primary key; the hidden link a T-tag resolves to |
| Key blob | encrypted-blob | The Session Key, wrapped by a randomly-selected System Key |
| Key number | counter | Sequence within the system |
| Flags | flag | Status bits |
| Created / Expired | timestamps | Lifecycle |
| Signature | signature | Per-record HMAC |
The T-tag itself is not a stored table — it is the client-side construct (System ID, System Key ID, encrypted Key ID) that resolves into these two entities. See Key Management Process.
Access-control entities
ACL
One ACL per protected key. SDK surface: TEACLInfo.
| Field | Logical type | Role |
|---|---|---|
| ACL ID | identifier | Primary identity |
| Hidden Link | link | To the protected key / data (indexed) |
| Creation time | timestamp | Lifecycle |
| Expiration | flag | Whether the ACL is expired |
| Signature | signature | Per-record HMAC |
ACL Entry
Many per ACL — one per-principal grant. SDK surface: TEACLEntry.
| Field | Logical type | Role |
|---|---|---|
| ACL ID | identifier | → ACL |
| Principal ID | identifier | → Principal |
| System ID | identifier | Owning system |
| ACL Right / User Right | flags | Granted rights |
| Max Usage | counter | Usage cap |
| Start / End / Creation time | timestamps | Validity window |
| Signature | signature | Per-record HMAC |
ACLs may be seeded from reusable templates — see TEACLTemplate and TEACLTemplateMember.
The per-link / T-tag status record (marking a link offline, for example) is not stored in the KDB — it lives in the Remote Engine's local store and is surfaced through TEAdminLocal. See Key Server Architecture → The rE local store and offline operation.
Principal and trust entities
Principal
A Principal is an identity that can be granted rights on a key. Logically it is a single entity with a subtype per authenticated principal type — each pairs a credential with its protocol: Password (SRP), Certificate (X.509), and LDAP (Kerberos) — the last stored here as a principal subtype, though the directory authenticator itself is build-dependent (see Key Management Process). A further Group principal is a collection used as a grant target for discretionary access control — rights granted to a group are inherited by its members. Each principal record carries its identity plus its group, role, and ACL-template associations. SDK surface: TEPrincipalInfo; group and role associations are TEGroupInfo and TEUserRole.
| Field | Logical type | Role |
|---|---|---|
| Principal ID | identifier | Primary identity |
| System ID | identifier | Owning system |
| Name / subject | string | The identity's name or subject |
| Groups / roles / templates | string lists | Associations |
| Flags | flag | Status bits |
| Signature | signature | Per-record HMAC |
Cross-server Trust
Records another kS this server trusts, enabling cross-kS key exchange. SDK surface: TETrustedServerInfo.
| Field | Logical type | Role |
|---|---|---|
| Principal ID / System ID | identifiers | The trusted server's identity |
| Server name | string | Host of the trusted server |
| Port | integer | Service port |
| Friendly name / Description | strings | Operator labels |
| Signature | signature | Per-record HMAC |
Principal Trust Matrix
Maps a local principal to a trusted server. SDK surface: TEPrincipalTrustMatrix.
| Field | Logical type | Role |
|---|---|---|
| Object ID | identifier | Primary identity |
| Principal ID | identifier | → Principal |
| Trusted Server ID | identifier | → Trusted Server |
| Flag | flag | Status |
| Signature | signature | Per-record HMAC |
Relationships
Linked Envelope (client-side; not a stored entity)
└─ T-tag ── carries ──▶ System Key ID ──▶ [System Key]
└─ T-tag ── resolves ─▶ Key link ───────▶ [Session Key]
[Session Key].blob ── wrapped by ─▶ a [System Key] (random selection)
[System Key].blob ── wrapped by ─▶ a Master Key (in the Master Key
Container, NOT the KDB)
[Session Key] ──1:1── [ACL] ──(via Hidden Link)
[ACL] ──1:N── [ACL Entry] ──N:1── [Principal]
[Principal] ──via── [Principal Trust Matrix] ──N:1── [Trusted Server]
every entity ── has ─▶ [Signature] (HMAC, signed by the Master HMAC Key)
The per-record signature
Every KDB record carries a Signature — an HMAC produced by the Master HMAC Key (one of the Master Keys; see Key Hierarchy and Bootstrapping). This is the KDB's integrity backbone: any tampering with a stored key, ACL, principal, or trust record is detectable, because the signature will no longer verify against the Master HMAC Key.
Audit and system entities
Beyond the key/ACL/principal/trust core, the KDB carries server-side audit and system bookkeeping. These are listed here for completeness; they are not part of the key-relationship model above:
- Audit & logging: audit log, event log (TEEventLog), error log, transaction log, and the operation catalog (TEOperation).
- Identity & access metadata: groups, roles, ACL templates, templated directories (TETemplatedDirectory), certificates (TECertObjectInfo), and code-signing identities (TECodeSigningInfo).
- System & counters: parameters (TEParameter), a key/value store with TTL, persistent-object counters (carrying the cluster instance ID) and recovery metadata.
Related pages
- Key Hierarchy and Bootstrapping — the keys whose wrapped forms and signatures the KDB stores.
- Key Server Architecture — the persistency layer that reads and writes the KDB.
- SDK Reference (C++) — the classes that mirror these entities.