PKCS7 and SMIME: improve documentation w.r.t. untrusted and signer certificates

Reviewed-by: Mounir Idrassi <[email protected]>
Reviewed-by: Dmitry Belyavskiy <[email protected]>
Reviewed-by: Eugene Syromiatnikov <[email protected]>
Merge-date: Thu Sep  3 09:26:56 2026
Merged-from: https://github.com/openssl/openssl/pull/22285

2 files changed, 19 insertions, 15 deletions

diff --git a/apps/cms.c b/apps/cms.c
index fff3b2fbeae..ee59b9faa07 100644
--- a/apps/cms.c
+++ b/apps/cms.c
@@ -226,8 +226,8 @@ const OPTIONS cms_options[] = {
     OPT_R_OPTIONS,
 
     OPT_SECTION("Encryption and decryption"),
-    { "originator", OPT_ORIGINATOR, 's', "Originator certificate file" },
-    { "recip", OPT_RECIP, '<', "Recipient cert file" },
+    { "originator", OPT_ORIGINATOR, 's', "Originator certificate" },
+    { "recip", OPT_RECIP, '<', "Recipient cert" },
     { "cert...", OPT_PARAM, '.',
         "Recipient certs (optional; used only when encrypting)" },
     { "", OPT_CIPHER, '-',
@@ -247,7 +247,7 @@ const OPTIONS cms_options[] = {
 
     OPT_SECTION("Signing"),
     { "md", OPT_MD, 's', "Digest algorithm to use" },
-    { "signer", OPT_SIGNER, 's', "Signer certificate input file" },
+    { "signer", OPT_SIGNER, 's', "Signer certificate input" },
     { "certfile", OPT_CERTFILE, '<',
         "Extra signer and intermediate CA certificates to include when signing" },
     { OPT_MORE_STR, 0, 0,
@@ -514,6 +514,10 @@ int cms_main(int argc, char **argv)
             break;
         case OPT_NOCERTS:
             flags |= CMS_NOCERTS;
+            /*
+             * Note that this does not affect certificates in variable 'other'
+             * containing extra certs loaded according to the -certfile option.
+             */
             break;
         case OPT_NOATTR:
             flags |= CMS_NOATTR;
@@ -982,7 +986,7 @@ int cms_main(int argc, char **argv)
 
         for (; *argv != NULL; argv++) {
             cert = load_cert(*argv, FORMAT_UNDEF,
-                "recipient certificate file");
+                "recipient certificate");
             if (cert == NULL)
                 goto end;
             if (!sk_X509_push(encerts, cert))
@@ -992,7 +996,7 @@ int cms_main(int argc, char **argv)
     }
 
     if (certfile != NULL
-        && !load_certs(certfile, 0, &other, NULL, "certificate file"))
+        && !load_certs(certfile, 0, &other, NULL, "extra certificates"))
         goto end;
 
     if (recipfile != NULL && (operation == SMIME_DECRYPT)
diff --git a/apps/smime.c b/apps/smime.c
index 7f639ebd5b8..fd817ca98bf 100644
--- a/apps/smime.c
+++ b/apps/smime.c
@@ -117,7 +117,7 @@ const OPTIONS smime_options[] = {
     { "nodetach", OPT_NODETACH, '-', "Use opaque signing" },
     { "noattr", OPT_NOATTR, '-', "Don't include any signed attributes" },
     { "binary", OPT_BINARY, '-', "Don't translate message to text" },
-    { "signer", OPT_SIGNER, 's', "Signer certificate file" },
+    { "signer", OPT_SIGNER, 's', "Signer certificate" },
     { "content", OPT_CONTENT, '<',
         "Supply or override content for detached signature" },
     { "nocerts", OPT_NOCERTS, '-',
@@ -127,11 +127,7 @@ const OPTIONS smime_options[] = {
     { "nosigs", OPT_NOSIGS, '-', "Don't verify message signature" },
     { "noverify", OPT_NOVERIFY, '-', "Don't verify signers certificate" },
 
-    { "certfile", OPT_CERTFILE, '<',
-        "Extra signer and intermediate CA certificates to include when signing" },
-    { OPT_MORE_STR, 0, 0,
-        "or to use as preferred signer certs and for chain building when verifying" },
-    { "recip", OPT_RECIP, '<', "Recipient certificate file for decryption" },
+    { "recip", OPT_RECIP, '<', "Recipient certificate for decryption" },
 
     OPT_SECTION("Email"),
     { "to", OPT_TO, 's', "To address" },
@@ -141,6 +137,10 @@ const OPTIONS smime_options[] = {
     { "nosmimecap", OPT_NOSMIMECAP, '-', "Omit the SMIMECapabilities attribute" },
 
     OPT_SECTION("Certificate chain"),
+    { "certfile", OPT_CERTFILE, '<',
+        "Extra signer and intermediate CA certificates to include when signing" },
+    { OPT_MORE_STR, 0, 0,
+        "or to use as preferred signer certs and for chain building when verifying" },
     { "CAfile", OPT_CAFILE, '<', "File in PEM format with trusted CA certs" },
     { "CApath", OPT_CAPATH, '/', "Dir with trusted CA cert files in PEM format" },
     { "CAstore", OPT_CASTORE, ':', "URI of store with trusted CA certs" },
@@ -151,8 +151,8 @@ const OPTIONS smime_options[] = {
     { "no-CAstore", OPT_NOCASTORE, '-',
         "Do not load certificates from the default certificates store" },
     { "nochain", OPT_NOCHAIN, '-',
-        "set PKCS7_NOCHAIN so certificates contained in the message are not used as untrusted CAs" },
-    { "crlfeol", OPT_CRLFEOL, '-', "Use CRLF as EOL termination instead of LF only" },
+        "Do not use certs contained in the message as untrusted CAs for chain building" },
+    { "crlfeol", OPT_CRLFEOL, '-', "Use CRLF as EOL termination (instead of LF only)" },
 
     OPT_R_OPTIONS,
     OPT_V_OPTIONS,
@@ -520,7 +520,7 @@ int smime_main(int argc, char **argv)
     }
 
     if (certfile != NULL) {
-        if (!load_certs(certfile, 0, &other, NULL, "certificates")) {
+        if (!load_certs(certfile, 0, &other, NULL, "extra certificates")) {
             ERR_print_errors(bio_err);
             goto end;
         }
@@ -624,7 +624,7 @@ int smime_main(int argc, char **argv)
             p7 = PKCS7_sign_ex(NULL, NULL, other, in, flags, libctx, app_get0_propq());
             if (p7 == NULL)
                 goto end;
-            if (flags & PKCS7_NOCERTS) {
+            if ((flags & PKCS7_NOCERTS) != 0) { /* still add list given via -certfile */
                 for (i = 0; i < sk_X509_num(other); i++) {
                     X509 *x = sk_X509_value(other, i);
                     PKCS7_add_certificate(p7, x);