Developer-Friendly Integration

Simple, secure, standards-based

Khatim PKI Server is built to be consumed by applications and automation pipelines. For external enrollment and automation protocols (SCEP, CMP, EST, ACME), we use the companion Khatim RA Server to handle those API front-doors. Once the request is accepted at the RA layer, it is forwarded to the Khatim PKI Server’s Certificate Provider (CP) engine which performs policy checks and issues the certificate. All inter-component communication is authenticated (OAuth) and logged for auditability.

External integrations (SCEP, CMP, EST, ACME) – how it flows

1. Client → RA Server
   Applications, devices or ACME clients talk to the Khatim RA Server using the standard protocol they support (SCEP/CMP/EST/ACME). The RA Server validates enrollment requests, performs MFA/approval flows if configured, and maps the request to an internal RA policy.

2. RA Server → CP Engine (Khatim PKI Server)
   Validated requests are forwarded to the Certificate Provider engine over the Khatim PKI Server’s protocol. Communication is authenticated with OAuth tokens and the CP verifies policy, HSM availability, and template constraints.

3. CP → Issuance
   The Certificate Provider issues, renews or revokes certificates using the mapped CA and KeyVault settings (HSM-backed keys if configured), returns the certificate chain and records the transaction for monitoring and audit.

4. Response → Client
   The RA Server transforms the CP response into the protocol-appropriate payload and returns it to the requesting client.

Certificate Provider (internal API) & Policy model

Khatim PKI Server’s Certificate Provider engine is an internal, RESTful based engine for certificate lifecycle operations. It exposes secure endpoints to:

• Issue certificates (from CSR or generate keys on the server)

• Renew certificates

• Revoke or unrevoke certificates

• Delete certificates

• Query certificate status & list account certificates

To call the CP APIs an operator or client app must:

1. Create a Certificate Provider (CP) policy – defines which CA issues the cert, which template (TLS, Code Signing, Email, etc.), key controls, key type/size, KeyVault target, subject DN rules and extensions.

2. Setup a client application – register the app in the server and assign one or more CP policies to it. Use OAuth credentials for authentication.

3. Send the request – call the CP REST endpoint with the CP policy ID and either a CSR (PKCS#10) or request server-side key generation.

Policy facets include:

• Issuing CA selection

• Certificate Template (controls EKU, KU, extensions, lifetime, hash algo)

• Key control: Server (HSM holds the key) or Client-CSR (caller supplies CSR)

• Key type & size (RSA, ECDSA, PQC where enabled)

• KeyVault / HSM slot for key generation/storage

• Subject DN templates and allowed attributes (20+ DN attributes supported)

Developer workflows & REST example

Typical server-side issuance (CSR):

Request

POST /api/certificate-provider/issue
Accept: application/json
Content-Type: multipart/form-data
Authorization: Bearer <oauth_token> Form fields: { "cpPolicyId": "client-rsa-cert", "raPolicyId": "rapolicy123", "accountId": "ahmad123", "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICVTC...fg==\n-----END CERTIFICATE REQUEST-----", "certAlias": "ahmad123" }

Response

{
  "responseStatus": "0",
  "issuedCertPem": "-----BEGIN CERTIFICATE-----\nMIIDhDCCA...sBOzjWyZGPBuR9A4fznhyohr+Fg1/A==\n-----END CERTIFICATE-----",
  "certAlias": "ahmad123",
  "accountCertsKeysId": 13,
  "caChain": "MIIHvQYJK...wujMQA="
}

Developers can also request server-side key generation by omitting csr and providing keySpec (e.g., RSA-2048) and keyVault pointing to an HSM slot; the issued certificate will be associated with the generated key and returned with metadata for later use.

Security & auditability

• OAuth authentication: All CP REST calls require OAuth tokens; tokens can be scoped to CP policies and permissions.

• Role-based access: Admins control which client apps can request which CP policies.

• Transaction logging: Every CP transaction (issue, renew, revoke) is recorded with full metadata (timestamp, policy, requestor IP, HSM key alias) for troubleshooting and compliance.

• No document storage: It does not retain the application payloads (input documents), only issuance metadata – ensuring privacy while preserving audit evidence.

Benefits for developers & ops

• Standards compatibility: SCEP/CMP/EST/ACME support via RA Server.

• Rapid integration: RESTful CP APIs with simple JSON/CSR payloads.

• Policy consistency: central templates and policies prevent drift.

• HSM-backed keys & KeyVault mapping for secure key custody.

• Full lifecycle control (issue, renew, revoke) through a single API.