apps/cmp.c: Improve documentation of -secret, -cert, and -key options

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12825)

diff --git a/apps/cmp.c b/apps/cmp.c
index 003c75517d66dcd61437658570cabfc0d0f68bf6..d0f3c020c1ba618952d349b8475d75c92b7fee9e 100644 (file)
--- a/apps/cmp.c
+++ b/apps/cmp.c
@@ -378,14 +378,16 @@ const OPTIONS cmp_options[] = {
     {"ref", OPT_REF, 's',
      "Reference value to use as senderKID in case no -cert is given"},
     {"secret", OPT_SECRET, 's',
-     "Password source for client authentication with a pre-shared key (secret)"},
+     "Prefer PBM (over signatures) for protecting msgs with given password source"},
     {"cert", OPT_CERT, 's',
-     "Client's current certificate (needed unless using -secret for PBM);"},
+     "Client's CMP signer certificate; its public key must match the -key argument"},
     {OPT_MORE_STR, 0, 0,
-     "any further certs included are appended in extraCerts field"},
+     "This also used as default reference for subject DN and SANs."},
+    {OPT_MORE_STR, 0, 0,
+     "Any further certs included are appended to the untrusted certs"},
     {"own_trusted", OPT_OWN_TRUSTED, 's',
      "Optional certs to verify chain building for own CMP signer cert"},
-    {"key", OPT_KEY, 's', "Private key for the client's current certificate"},
+    {"key", OPT_KEY, 's', "CMP signer private key, not used when -secret given"},
     {"keypass", OPT_KEYPASS, 's',
      "Client private key (and cert and old cert file) pass phrase source"},
     {"digest", OPT_DIGEST, 's',
@@ -1479,8 +1481,8 @@ static SSL_CTX *setup_ssl_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine)
  */
 static int setup_protection_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine)
 {
-    if (!opt_unprotected_requests && opt_secret == NULL && opt_cert == NULL) {
-        CMP_err("must give client credentials unless -unprotected_requests is set");
+    if (!opt_unprotected_requests && opt_secret == NULL && opt_key == NULL) {
+        CMP_err("must give -key or -secret unless -unprotected_requests is used");
         return 0;
     }
 
@@ -1507,7 +1509,7 @@ static int setup_protection_ctx(OSSL_CMP_CTX *ctx, ENGINE *engine)
                 return 0;
         }
         if (opt_cert != NULL || opt_key != NULL)
-            CMP_warn("no signature-based protection used since -secret is given");
+            CMP_warn("-cert and -key not used for protection since -secret is given");
     }
     if (opt_ref != NULL
             && !OSSL_CMP_CTX_set1_referenceValue(ctx, (unsigned char *)opt_ref,

diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index 44f71b8358674925ea0483cca73c286f4065ff21..2d484805b3f7ad5f04b55c5498ff79fbd5103abe 100644 (file)
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -610,10 +610,11 @@ is typically used when authenticating with pre-shared key (password-based MAC).
 
 =item B<-secret> I<arg>
 
-Source of secret value to use for creating PBM-based protection of outgoing
-messages and for verifying any PBM-based protection of incoming messages.
+Prefer PBM-based message protection with given source of a secret value.
+The secret is used for creating PBM-based protection of outgoing messages
+and (as far as needed) for verifying PBM-based protection of incoming messages.
 PBM stands for Password-Based Message Authentication Code.
-This takes precedence over the B<-cert> option.
+This takes precedence over the B<-cert> and B<-key> options.
 
 For more information about the format of B<arg> see the
 B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
@@ -624,13 +625,17 @@ The client's current CMP signer certificate.
 Requires the corresponding key to be given with B<-key>.
 The subject of this certificate will be used as sender of outgoing CMP messages,
 while the subject of B<-oldcert> or B<-subjectName> may provide fallback values.
+The issuer of this certificate is used as one of the recipient fallback values.
 When using signature-based message protection, this "protection certificate"
-will be included first in the extraCerts field of outgoing messages.
+will be included first in the extraCerts field of outgoing messages
+and the signature is done with the corresponding key.
 In Initialization Request (IR) messages this can be used for authenticating
 using an external entity certificate as defined in appendix E.7 of RFC 4210.
 For Key Update Request (KUR) messages this is also used as
 the certificate to be updated if the B<-oldcert> option is not given.
-If the file includes further certs, they are appended to the untrusted certs.
+If the file includes further certs, they are appended to the untrusted certs
+because they typically constitute the chain of the client certificate, which
+is included in the extraCerts field in signature-protected request messages.
 
 =item B<-own_trusted> I<filenames>