Interfaces and integration
Summary. WKL TrustBridge distinguishes four kinds of interfaces: standard protocols for partner systems (ACME, EST, CMP); public distribution of CA certificates, CRLs, and trust bundles over HTTP; a business-level management API for the management application, the partner portal, and automation; and the local interfaces of the TLS adapter and key agent on every connected host. Standardized endpoints are implemented unchanged; a proprietary interface exists only where there is no standard. Every path leads to the same business operations and the same permissions.
Terms
- Protocol adapter – a component that implements a standard protocol completely (messages, signatures, states, error formats) and hands the business decision to the shared core.
- Business core – management and the enrollment core: authorization, tenant, building the order, audit.
- OData v4 – an OASIS and ISO/IEC standard for REST interfaces with a machine-readable schema, query options, and actions.
- Command – an operation that affects more than one row, creates an order, or returns a secret; implemented as an OData action or
POST.
Overview
graph TD
subgraph EXT [Standard protocols]
ACME[ACME<br/>RFC 8555]
EST[EST<br/>RFC 7030]
CMP[Lightweight CMP<br/>RFC 9483]
end
subgraph MGM [Business API]
OD[Management API<br/>OData v4, actions]
end
subgraph PUB [Public distribution]
AIA[CA certificates<br/>HTTP GET]
CDP[CRLs<br/>HTTP GET]
TB[Trust bundles<br/>HTTP GET]
end
PS[Partner systems] --> ACME
PS --> EST
PS --> CMP
ADM[Management application] --> OD
PP[Partner portal] --> OD
AUT[Automation] --> OD
PR[Relying parties] --> AIA
PR --> CDP
TLA[TLS adapters, key agents] --> TB
ACME --> K[Business core]
EST --> K
CMP --> K
OD --> K
K --> DB[(Orders)]
classDef std fill:#deecf9,stroke:#0078d4,color:#201f1e
classDef own fill:#f3f2f1,stroke:#605e5c,color:#201f1e
classDef par fill:#deecf9,stroke:#0078d4,color:#201f1e
classDef onl fill:#f3f2f1,stroke:#605e5c,color:#201f1e
class ACME,EST,CMP,AIA,CDP,TB std
class OD,K,PP own
class ADM,AUT,PR,PS,TLA par
class DB onl
style EXT fill:#ffffff,stroke:#8a8886,color:#201f1e
style MGM fill:#ffffff,stroke:#8a8886,color:#201f1e
style PUB fill:#ffffff,stroke:#8a8886,color:#201f1ePrinciple: standards unchanged, a proprietary API only where none exists
A partner system should not need a TrustBridge-specific client for ordinary PKI operations. Standardized endpoints are therefore implemented exactly as the specification describes them, including their paths and error formats, rather than being translated into a naming convention of our own. The large private CA vendors follow the same pattern: systems speak IETF protocols, management uses a dedicated, resource-oriented API.
Protocol adapters
The wrapper principle. An adapter is complete in the protocol and thin in business logic:
| Responsibility | Adapter | Business core |
|---|---|---|
| HTTP protocol, message formats, protocol signatures | Yes | No |
| Protocol states (such as ACME order, nonce) | Yes | No |
| Authorization | Supplies the context (account, client certificate) | Decides |
| Checking the request against profile class and namespace | No | Yes |
| Building the order, attesting automatic classes | No | Yes |
| Audit | Supplies protocol events | Writes the security audit log |
| Errors | Translates into the protocol's format | Supplies business errors |
The core does not need to know what an ACME order is; it understands that an authorized participant is requesting a certificate for a particular identity in a particular profile class. Signing happens neither in the adapter nor in the core but later, in the CA worker; no adapter waits for the signature.
ACME (RFC 8555)
| Aspect | Definition |
|---|---|
| Entry point | A directory at a freely chosen address; the names of the operations (newNonce, newAccount, newOrder, revokeCert, keyChange) are standardized, their paths are not |
| Binding to the tenant | ACME accounts are bound to a tenant through External Account Binding; an account without binding gets nothing |
| Proof of name control | http-01, dns-01, or tls-alpn-01 for names within the partner's namespace; the profile class defines which types are allowed for each partner |
| Issuance | Finalizing the order creates a TrustBridge order; the certificate can be retrieved once the worker has issued it (ACME provides for asynchronous processing) |
| Revocation | revokeCert with proof of the certificate's key, or by the account |
EST (RFC 7030)
| Endpoint | Use |
|---|---|
/.well-known/est/cacerts | Retrieve the CA certificates |
/.well-known/est/simpleenroll | Initial issuance, authenticated through the proof required by the profile class (one-time value, device certificate, or TPM attestation) |
/.well-known/est/simplereenroll | Renewal with the current certificate |
/.well-known/est/serverkeygen | Server-side key generation: not offered; TrustBridge generates no keys for requesters |
Additional path segments per CA or profile are allowed under RFC 7030.
Lightweight CMP (RFC 9483)
Lightweight CMP is widespread in industrial devices and controllers. TrustBridge offers it for profile classes for machines and devices, with the manufacturer certificate (IEEE 802.1AR) as proof for initial provisioning. As with ACME and EST, the adapter only creates an order; signing happens in the CA worker.
SCEP
SCEP is not offered. It authenticates initial provisioning with a shared challenge password, which does not meet the requirements for initial provisioning. Device management systems that speak only SCEP are connected through an upstream service that speaks EST or CMP.
Management API
The management API is the single business interface for the management application, the partner portal, and automation. All of them go through the same checks, permissions, and audit entries; whether a command comes from Access or from a script makes no difference.
| Aspect | Definition |
|---|---|
| Form | OData v4: entity sets for reading (filtering, sorting, paging, counting, grouping), actions for commands; a machine-readable schema; an OpenAPI description generated from it for tools without OData |
| Names | English resource and field names (such as certificates, certificate-requests, trust-relationships) |
| Commands | Create orders and respond as soon as they are stored; no command waits for the worker |
| Idempotency | Idempotency-Key on every write call; a repeat receives the first response |
| Write conflicts | Row version as ETag, If-Match, response 412 |
| Errors | OData error format with a fixed code and a message in the caller's language; never a key, a signature, or a verbatim database error |
| Tenants | An object outside the caller's visibility scope is 404, not 403 |
| Signing in as a person | Personal key in a header; second factor through a challenge (401 pointing to the address where a one-time code is exchanged for a session); for every person, even read-only. In Windows domains, alternatively Windows sign-in through Kerberos |
| Signing in as a program | mTLS with a client certificate from the organization's own CA |
| Ad hoc database statements, transactions spanning several requests | Not offered |
| Versions | Major version in the path; end of a version announced through the Deprecation (RFC 9745) and Sunset (RFC 8594) headers, with a minimum notice of twelve months |
Why OData rather than plain REST lists. The management application links lists through an ODBC driver that speaks only OData; it cannot link plain REST lists. OData is a REST standard, and the OpenAPI description generated from it serves tools without OData. A second REST read surface next to the OData entity sets would deliver the same data twice and would have to be authorized and tested twice.
Why no OAuth for people. The management application's ODBC driver supports keys in a header, Windows sign-in, and Basic authentication, but no bearer tokens. For people, therefore, sign-in stays with the personal key plus a second factor.
Security analysis of sign-in for people
Sign-in for people (a personal key in a header, a second factor through a one-time code, a session in a header) is shaped by what the management application's ODBC driver can do. That shaping must not set the security level, so the following analysis assesses the sign-in against the relevant threats.
| Threat | Assessment | Measure | Remaining risk |
|---|---|---|---|
| Copying the personal key | The key is a bearer secret (256 bits of randomness), stored in the Windows account's credential store; malware with user rights can read it | Second factor for every person; an expiry date per key; origin rules (network ranges) | A copied key alone is not enough; together with an intercepted code it is |
| Intercepting the one-time code (real-time phishing) | One-time codes from an app are not phishing-resistant | Origin rules; a code is valid only once | Remains; the driver does not support phishing-resistant methods (FIDO2, smart card) |
| Replaying a request | Transport over TLS; every one-time code is accepted exactly once; write calls carry an idempotency key, and a repeat receives the first response without taking effect twice | M-40, idempotency | Low |
| Theft of the session token | The session is valid only together with the key it was opened with; a token alone opens nothing | Binding to person, method, and key | No binding to device or TLS channel; malware on the same workstation can piggyback on the session |
| Expiry | Sessions end after a fixed duration; keys have an expiry date | M-44 | Misuse within the session duration |
| Loss of the device | The key sits in the lost device's credential store; the one-time code app on the phone | Revoking the key immediately ends all sessions bound to it; another authorized person resets the second factor, with an audit entry | The time until the loss is reported |
| Withdrawal of permissions | Permissions are checked on every request, not cached in the session | M-43 | None beyond the current request |
| A staff member's compromised workstation | An attacker acts with the person's permissions while the session lasts: propose and cancel orders, trigger revocations, read | Approvals need a separate approval key on dedicated hardware with confirmation by the person (M-45); two-person rule in sensitive classes | Malware can falsify how an order is displayed; only a second, independent approval or a display on the approval device helps against that |
Windows sign-in. In Windows domains, people can sign in through Kerberos (Negotiate) instead. That removes the stored bearer secret; with smart card sign-in to Windows, the sign-in is phishing-resistant. Security then depends on the domain; each organization chooses the method for its people.
Approval through the API
An approval is not a signed-in confirmation but the person's signature over the hash of the order. The flow through the API:
sequenceDiagram participant P as Person participant A as Management application participant V as Management API P->>A: open order A->>V: retrieve order bytes V-->>A: bytes, unchanged A->>A: compute SHA-256, compare with identifier,<br/>display content from exactly these bytes P->>A: approve A->>A: sign hash with personal key A->>V: action: submit approval (signature) V->>V: store, do not verify Note over V: The CA worker does the verification
The API vouches for nothing and does not verify the signature; it passes it on. The approval key lives on a smart card or a security key with PIV support and requires the person's PIN for every signature.
States and errors
Commands in the management API change states only in the database; the CA worker's result appears later as a projection. For the management application this means: after a command, re-read the order rather than waiting for a response from the worker.
| State of an order in the API | Meaning | Possible commands |
|---|---|---|
| Pending approval | Stored, waiting for approvals | Submit approval, cancel |
| Approval complete | Approvals are in | Cancel |
| Claimed | The worker is processing it | None |
| Issued / rejected | Result from the ledger | None; with a reason if rejected |
| Canceled, expired | Final | None |
| Status | Use |
|---|---|
400 | Invalid input (such as a CSR without proof of possession, a name outside the namespace, an invalid revocation reason) |
401 | Not signed in, or second factor required |
403 | Signed in, but without the necessary permission |
404 | Does not exist, or outside the visibility scope |
409 | The state does not allow the command (such as approving a canceled order) |
412 | Outdated row version |
503 | Data store unreachable |
The CA worker sets the transition to “approval complete”, because only it knows the approval rules in its rule set. Until then, the API shows the approvals submitted.
Management application
The management application is the tool used by the staff of an organization and its operating partner (system administration, partner management, support). It is an Access application that talks exclusively to the management API: lists are linked OData entity sets, and commands run through a VBA class. A database connection from the client is ruled out.
Partner portal
The partner portal is the web interface for the people responsible at a partner whose issuing CA sits in the customer's hierarchy. It uses the same management API with one visibility scope per partner: file requests, approve their own orders, view inventory and revocation status of their own namespace, trigger revocations. Partners with an installation of their own use their own management application.
Interfaces on the connected host
| Interface | Use |
|---|---|
| Outbound port of the TLS adapter | The local application connects to a local address; the adapter opens the protected connection to the counterpart |
| Inbound port of the TLS adapter | The adapter accepts partner connections and forwards them to the local application |
| Passing on the partner identity | For HTTP, in headers carrying organization, service name, relationship, and purpose; the application must be reachable only through the adapter |
| Key broker interface | Only for the TLS adapter's service account, with operating system access control |
| Certificates of adapter and agent | Renewed automatically through ACME or EST at the organization's own CA |
| Status query | Local query of relationships, validity of secrets, last exchange, and recent rejections, without key material |
What this page does not define
- SCEP, or key generation for requesters.
- Identity provisioning for short-lived workloads through the SPIFFE Workload API. TrustBridge assigns exactly one DNS name per system; URI names are not provided for.
- The design of the management application and the partner portal. This page describes the interface they use, not their user interface.
Sources
- RFC 8555 – ACME: directory, accounts, orders, challenges, External Account Binding (Section 7.3.4).
- RFC 7030 – EST: endpoints under
/.well-known/est/, authentication, optional path segments. - RFC 9483 – Lightweight CMP Profile: profile for industrial devices.
- OData Version 4.01: protocol, schema format, query options.
- RFC 9745 – Deprecation header and RFC 8594 – Sunset header: announcing the end of an API version.