Commit 44635ff58b for openssl.org

commit 44635ff58b34e677b1bcf4bd87be07c4698d414c
Author: Dr. David von Oheimb <dev@ddvo.net>
Date:   Sun Aug 9 17:04:04 2026 +0200

    OSSL_CMP_{exec_certreq,SRV_CTX}_new.pod: enrich doc of CMP client and server

    In particular, clarify that they focus on the Lightweight CMP Profile
    and that the server is single-threaded.

    Reviewed-by: Andrew Dinh <andrewd@openssl.org>
    Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
    MergeDate: Thu Aug 27 07:24:59 2026
    (Merged from https://github.com/openssl/openssl/pull/28988)

diff --git a/doc/man3/OSSL_CMP_SRV_CTX_new.pod b/doc/man3/OSSL_CMP_SRV_CTX_new.pod
index aac88bafcc..e82c46b800 100644
--- a/doc/man3/OSSL_CMP_SRV_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_SRV_CTX_new.pod
@@ -94,15 +94,24 @@ OSSL_CMP_SRV_CTX_set_grant_implicit_confirm

 =head1 DESCRIPTION

-OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
-Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and the CMP request message
+OSSL_CMP_SRV_process_request() implements the generic core aspects
+of Certificate Management Protocol (CMP) servers.
+Its arguments are the B<OSSL_CMP_SRV_CTX> I<srv_ctx> and a CMP request message
 I<req>. It does the typical generic checks on I<req>, calls
 the respective callback function (if present) for more specific processing,
-and then assembles a result message, which may be a CMP error message.
+and then assembles a response message, which may be a CMP error message.
+
+Since OSSL_CMP_SRV_process_request() handles only a single CMP request message,
+it may need to be called multiple times until a CMP transaction has ended.
 If after return of the function the expression
 I<OSSL_CMP_CTX_get_status(OSSL_CMP_SRV_CTX_get0_cmp_ctx(srv_ctx))> yields -1
 then the function has closed the current transaction,
 which may be due to normal successful end of the transaction or due to an error.
+Otherwise, it should be called again with the next request message of the same
+transaction (which can be a certificate confirmation or a poll request message).
+The function should not be called by multiple threads sharing
+the same I<srv_ctx> without explicitly serialising the calls;
+calling it in parallel leads to undefined behavior.

 OSSL_CMP_CTX_server_perform() is an interface to
 OSSL_CMP_SRV_process_request() that can be used by a CMP client
@@ -160,11 +169,21 @@ confirmation of newly enrolled certificates if requested.

 CMP is defined in RFC 9810 (and CRMF in RFC 4211).

-So far the CMP server implementation is limited to one request per CMP message
-(and consequently to at most one response component per CMP message).
+Like the OpenSSL CMP client, the CMP server implementation documented here
+focuses on the Lightweight CMP Profile (RFC 9483).
+Among other things, this implies that only commonly used CMP message types are supported
+and that each CMP message may not contain multiple certificate requests or responses.
+
+So far, this server implementation is single-threaded and
+should not be called in parallel for any given B<OSSL_CMP_SRV_CTX> I<srv_ctx>.
+It can handle only one CMP transaction at a time (which, of course, is not a problem
+for transactions consisting of just a single request/response message pair).

 =head1 RETURN VALUES

+OSSL_CMP_SRV_process_request() returns a CMP response message, which may be an
+error message, or NULL on internal errors that preclude producing a response.
+
 OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
 NULL on error.

diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod
index e210c6e6b5..25867fdf43 100644
--- a/doc/man3/OSSL_CMP_exec_certreq.pod
+++ b/doc/man3/OSSL_CMP_exec_certreq.pod
@@ -51,8 +51,9 @@ OSSL_CMP_get1_certReqTemplate
                                    OSSL_CMP_ATAVS **keySpec);
 =head1 DESCRIPTION

-This is the OpenSSL API for doing CMP (Certificate Management Protocol)
-client-server transactions, i.e., sequences of CMP requests and responses.
+This is the OpenSSL main API for Certificate Management Protocol (CMP) clients.
+Each of the OSSL_CMP_exec_*() functions performs a whole CMP transaction,
+which is a sequence of related CMP request messages and response messages.

 All functions take a populated OSSL_CMP_CTX structure as their first argument.
 Usually the server name, port, and path ("CMP alias") need to be set, as well as
@@ -185,8 +186,9 @@ Both must be freed by the caller.

 CMP is defined in RFC 9810 (and CRMF in RFC 4211).

-The CMP client implementation is limited to one request per CMP message
-(and consequently to at most one response component per CMP message).
+This CMP implementation focuses on the Lightweight CMP Profile (RFC 9483).
+Among other things, this implies that only commonly used CMP message types are supported
+and that each CMP message may not contain multiple certificate requests or responses.

 When a client obtains from a CMP server CA certificates that it is going to
 trust, for instance via the caPubs field of a certificate response or using