Stateful Architecture - dogtagpki/pki GitHub Wiki

Overview

This page describes the current stateful architecture used in PKI 11.4. In the future it might be converted into a stateless architecture.

Certificate Profiles

In CA the certificate profiles are managed by the profile subsystem. The AbstractProfileSubsystem provides the base implementation. The ProfileSubsystem provides the implementation for file-based profiles which is the default. The LDAPProfileSubsystem provides the implementation for LDAP-based profiles which is mainly used in IPA.

When PKI server is started the profile subsystem will load the profile configuration from files or LDAP and store the Profile objects in memory. If the admin updates the profile configuration, both the profile configuration in file/LDAP and the profile object in memory will be updated.

In LDAPProfileSubsysstem when PKI server is started it will start a ProfileChangeMonitor thread which will start a persistent search against the profile subtree in ou=certificateProfiles,ou=ca,<suffix>. The thread will initially load all profile configuration stored in the subtree, create the profile objects based on the configuration, then listen to changes in the subtree. If there’s a change in the subtree, the old profile object will be discarded and a new profile object will be created.

The file-based ProfileSubsystem does not have such monitor. Any change in profile configuration files will require restarting PKI server.

Lightweight CA (LWCA)

The lightweight CAs are managed by CA subsystem. LWCA is only supported in IPA since it requires an IPA-specific key retriever tool to work properly in cluster environment.

When PKI server started, it will create an AuthorityMonitor thread which will start a persistent search against the LWCA subtree in ou=authorities,ou=ca,<suffix>. The thread will initially load all LWCA configuration stored in the subtree, create the LWCA objects based on the configuration, then listen to changes in the subtree. If there’s a change in the subtree, the old LWCA object will be discarded and a new LWCA object will be created.

If the signing cert or key of the LWCA doesn’t exist yet on the server, the AuthorityMonitor will create a KeyRetriever-<ID> thread for the LWCA which will retrieve the cert and key from another host in the cluster.

CRL Generation

When PKI server is started it will initialize the CRL issuing points and start CertStatusUpdateTask and RetrieveModificationTask threads.

Each CRL issuing points maintain lists of revoked certs, unrevoked certs, and expired certs in memory. When the CA revokes/unrevokes a cert, or when a cert becomes expired, these lists will be updated.

The CertStatusUpdateTask will periodically run LDAP searches to find not-yet-valid certs that have become valid, valid certs that have become expired, and revoked certs that have become expired, then update the cert status in LDAP. It will also update the list of expired cts in all CRL issuing points.

The RetrieveModificationTask will start a persistent search to monitor cert status changes in LDAP. If a cert is revoked/unrevoked in LDAP, the thread will the list of revoked/unrevoked certs in all CRL issuing points.

Each CRL issuing point also runs a CRLIssuingPoint-<ID> thread to periodically generate a CRL and publish the CRL.

Serial Number Range Management

When CA is started it will start a SerialNumberUpdateTask thread which will find the largest serial number in LDAP and update the counter of remaining RSNv1 numbers in range in CS.cfg. If there are only few numbers remaining, CA will allocate a new range in LDAP for the server.

When the CA creates a new cert or cert request, if there’s no more available serial number in the range it will switch to the new serial number range.

KRA also has a KeyStatusUpdateTask thread that does the same process for keys and key requests.

ACME Responder

When PKI server is started, the ACME responder will create an LDAPConfigMonitor thread which will start a persistent search to monitor changes in ACME configuration stored in LDAP. This is mechanism is used to manage ACME responders on all servers in the cluster.

OCSP Responder

When PKI server is started, OCSP responder will create a DefStore that stores the following information in memory:

  • a cache for CRL issuing points

  • the number of CRL updates since startup

  • the number of requests for each CRL issuing point since startup

The OCSP responder will also start a DefStoreCRLUpdater thread that will periodically clear the CRL issuing point cache.

When the OCSP responder receives a request, it will try to find the CRL issuing point in LDAP, then store it in the cache.

Job Scheduler

Each PKI subsystem has a job scheduler. The scheduler keeps the following information in memory:

  • job plugins

  • job instances

  • job threads

  • scheduler thread

When PKI server is started, it will load job scheduler configuration and create the job plugins and instances, It will also start a JobScheduler thread that will wake up periodically and find jobs instances that match the schedule. Then it will create to run the job in the background.

If the configuration is updated, the server will need to be restarted.

If all servers in the cluster have identical job scheduler configuration, the same jobs will be executed on multiple servers simultaneously, which in the best case could cause redundancy and in the worst case could cause race conditions.

⚠️ **GitHub.com Fallback** ⚠️