apps/cmp: extend documentation and diagnostics for using -reqin in special situations

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/21660)

2 files changed, 23 insertions, 5 deletions

diff --git a/apps/cmp.c b/apps/cmp.c
index 321feb6275..e289fd8ebd 100644
--- a/apps/cmp.c
+++ b/apps/cmp.c
@@ -1586,13 +1586,15 @@ static int setup_request_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine)
             && opt_popo != OSSL_CRMF_POPO_NONE
             && opt_popo != OSSL_CRMF_POPO_RAVERIFIED) {
             if (opt_csr != NULL) {
-                CMP_err1("no -newkey option given with private key for POPO, -csr option only provides public key%s",
-                        opt_key == NULL ? "" :
-                        ", and -key option superseded by -csr");
+                CMP_err1("no -newkey option given with private key for POPO, -csr option provides just public key%s",
+                         opt_key == NULL ? "" :
+                         ", and -key option superseded by -csr");
+                if (opt_reqin != NULL)
+                    CMP_info("since -reqin is used, may use -popo -1 or -popo 0 to disable the needless generation of a POPO");
                 return 0;
             }
             if (opt_key == NULL) {
-                CMP_err("missing -newkey (or -key) option for POPO");
+                CMP_err("missing -newkey (or -key) option for key to be certified and for POPO");
                 return 0;
             }
         }
@@ -1696,7 +1698,7 @@ static int setup_request_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine)
 
     if (opt_recipient == NULL && opt_srvcert == NULL && opt_issuer == NULL
             && opt_oldcert == NULL && opt_cert == NULL)
-        CMP_warn("missing -recipient, -srvcert, -issuer, -oldcert or -cert; recipient will be set to \"NULL-DN\"");
+        CMP_warn("missing -recipient, -srvcert, -issuer, -oldcert or -cert; recipient for any requests not covered by -reqin will be set to \"NULL-DN\"");
 
     if (opt_cmd == CMP_P10CR || opt_cmd == CMP_RR || opt_cmd == CMP_GENM) {
         const char *msg = "option is ignored for 'p10cr', 'rr', and 'genm' commands";
diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index 9b8fe8844d..fade86fdde 100644
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -988,9 +988,25 @@ Default is one invocation.
 Take the sequence of CMP requests to send to the server from the given file(s)
 rather than from the sequence of requests produced internally.
 
+This option is useful for supporting offline scenarios where the certificate
+request (or any other CMP request) is produced beforehand and sent out later.
+
 This option is ignored if the B<-rspin> option is given
 because in the latter case no requests are actually sent.
 
+Note that in any case the client produces internally its sequence
+of CMP request messages. Thus, all options required for doing this
+(such as B<-cmd> and all options providing the required parameters)
+need to be given also when the B<-reqin> option is present.
+
+Hint: In case the B<-reqin> option is given for a certificate request,
+there are situations where the client has access to
+the public key to be certified (e.g., via the B<-newkey> or B<-csr> options) but
+not to the private key that by default will be needed for proof of possession.
+In this case the POPO is not actually needed (because the internally produced
+certificate request message will not be sent), and its generation
+can be disabled using the options B<-popo> I<-1> or B<-popo> I<0>.
+
 Multiple filenames may be given, separated by commas and/or whitespace
 (where in the latter case the whole argument must be enclosed in "...").