From 6064dda94b32326ccbd4ffbf354fde5535ddb55d Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Thu, 5 Oct 2023 23:07:06 +0200 Subject: [PATCH] fixup! PKCS7 and SMIME: improve documentation w.r.t. untrusted and signer certificates --- apps/cms.c | 6 +++--- apps/smime.c | 6 +++--- doc/man1/openssl-cms.pod.in | 28 +++++++++++++++++----------- doc/man1/openssl-smime.pod.in | 30 ++++++++++++++++++------------ doc/man3/CMS_add0_cert.pod | 11 +++++++---- doc/man3/CMS_verify.pod | 2 +- doc/man3/PKCS7_sign_add_signer.pod | 14 ++++++-------- doc/man3/PKCS7_verify.pod | 18 +++++++++--------- 8 files changed, 64 insertions(+), 51 deletions(-) diff --git a/apps/cms.c b/apps/cms.c index d09f0c09020bb..7065e0215ea6e 100644 --- a/apps/cms.c +++ b/apps/cms.c @@ -176,9 +176,9 @@ const OPTIONS cms_options[] = { {"md", OPT_MD, 's', "Digest algorithm to use"}, {"signer", OPT_SIGNER, 's', "Signer certificate input file"}, {"certfile", OPT_CERTFILE, '<', - "Other certificates to include when signing or to use when verifying;"}, + "Extra signer and intermediate CA certificates to include when signing"}, {OPT_MORE_STR, 0, 0, - "may be used for chain building and as signer cerificates"}, + "or to use as preferred signer certificates when verifying"}, {"cades", OPT_CADES, '-', "Include signingCertificate attribute (CAdES-BES)"}, {"nodetach", OPT_NODETACH, '-', "Use opaque signing"}, @@ -846,7 +846,7 @@ int cms_main(int argc, char **argv) } if (certfile != NULL) { - if (!load_certs(certfile, 0, &other, NULL, "other certificates")) { + if (!load_certs(certfile, 0, &other, NULL, "extra certificates")) { ERR_print_errors(bio_err); goto end; } diff --git a/apps/smime.c b/apps/smime.c index b97d2c63ba91a..33da4171b93c7 100644 --- a/apps/smime.c +++ b/apps/smime.c @@ -107,9 +107,9 @@ const OPTIONS smime_options[] = { OPT_SECTION("Certificate chain"), {"certfile", OPT_CERTFILE, '<', - "Other certificates to include when signing or to use when verifying;"}, + "Extra signer and intermediate CA certificates to include when signing"}, {OPT_MORE_STR, 0, 0, - "may be used for chain building and as signer cerificates"}, + "or to use as preferred signer certificates when verifying"}, {"CApath", OPT_CAPATH, '/', "Trusted certificates directory"}, {"CAfile", OPT_CAFILE, '<', "Trusted certificates file"}, {"CAstore", OPT_CASTORE, ':', "Trusted certificates store URI"}, @@ -494,7 +494,7 @@ int smime_main(int argc, char **argv) } if (certfile != NULL) { - if (!load_certs(certfile, 0, &other, NULL, "other certificates")) { + if (!load_certs(certfile, 0, &other, NULL, "extra certificates")) { ERR_print_errors(bio_err); goto end; } diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 9f96545008502..413f30bfdce02 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -447,15 +447,21 @@ default digest algorithm for the signing key will be used (usually SHA1). =item B<-signer> I -A signing certificate. When signing or resigning a message, this option can be +A signer certificate. When signing or resigning a message, this option can be used multiple times if more than one signer is required. =item B<-certfile> I -Provide additional certificates. -When signing, these will be included -in the message to help chain building and to provide extra signer certificates. -When verifying, these will be searched first for signer certificates. +Provide extra certificates. +When signing, these will be included in the message and can serve +both as candidate untrusted CA certificates for chain building in verification +and as fallback signer certificates. +When verifying, the provided certificates take precedence over the +signer certificates in the message as a source of candidate signers. +With B<-nointern> these will be the only signer certificates considered. + +Note that a message can have multiple signers. +When verifying a multi-signed message, all the signatures must be valid, and so all the signer certificates need to be available. The input can be in PEM, DER, or PKCS#12 format. @@ -475,9 +481,9 @@ the MIME type multipart/signed is used. =item B<-nocerts> -When signing a message, the signer's certificate it normally -included, but this option disables its inclusion. This will reduce the size of -the signed message but the verifier must have a copy of the signers certificate +When signing a message, the signer certificates are normally included, +but this option disables their inclusion. This will reduce the size of the +signed message but the verifier must then have a copy of the signer certificates available locally (passed using the B<-certfile> option for example). =item B<-noattr> @@ -545,10 +551,10 @@ Do not verify the signers certificate of a signed message. =item B<-nointern> When verifying a message, normally certificates (if any) included in -the message are searched for the signing certificate. With this option, +the message are searched for the signer certificates. With this option, only the certificates given with the B<-certfile> option are used. -However, the certificates included in -the message are still used for chain building as certificates of untrusted CAs. +However, the certificates included in the message are still used +as candidate intermediate CA certificates during chain construction. =item B<-cades> diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in index b4f89c2754682..5188017e3bfa5 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -178,10 +178,10 @@ If not specified triple DES is used. Only used with B<-encrypt>. =item B<-nointern> When verifying a message, normally certificates (if any) included in -the message are searched for the signing certificate. With this option, +the message are searched for the signer certificates. With this option, only the certificates given with the B<-certfile> option are used. -However, unless the B<-nochain> option is given, the certificates included in -the message are still used for chain building as certificates of untrusted CAs. +However, the certificates included in the message are still used +as candidate intermediate CA certificates during chain construction. =item B<-noverify> @@ -189,8 +189,8 @@ Do not verify the signers certificate of a signed message. =item B<-nochain> -During chain verification of signer certificates, do not use the certificates -in the signed message as untrusted CA certificates for chain building. +When verifying the signer certificates of a signed message, do not use the +certificates in the message as candidate CA certificates for chain building. =item B<-nosigs> @@ -198,10 +198,10 @@ Don't try to verify the signatures on the message. =item B<-nocerts> -When signing a message, the signer's certificate and chain certificates are +When signing a message, the signer certificates and chain certificates are normally included, but this option disables their inclusion. -This will reduce the size of -the signed message but the verifier must have a copy of those certificates +This will reduce the size of the +signed message but the verifier must then have a copy of those certificates available locally (passed using the B<-certfile> option for example). =item B<-noattr> @@ -235,16 +235,22 @@ option is present B is used instead. =item B<-certfile> I -Provide additional certificates. +Provide extra certificates. When signing, these will be included (unless the B<-nocerts> option is given) -in the message to help chain building and to provide extra signer certificates. -When verifying, these will be searched first for signer certificates. +in the message and can serve both as candidate untrusted CA certificates +for chain building in verification and as fallback signer certificates. +When verifying, the provided certificates take precedence over the +signer certificates in the message as a source of candidate signers. +With B<-nointern> these will be the only signer certificates considered. + +Note that a message can have multiple signers. +When verifying a multi-signed message, all the signatures must be valid, and so all the signer certificates need to be available. The input can be in PEM, DER, or PKCS#12 format. =item B<-signer> I -A signing certificate when signing or resigning a message, this option can be +A signer certificate when signing or resigning a message, this option can be used multiple times if more than one signer is required. If a message is being verified then the signers certificates will be written to this file if the verification was successful. diff --git a/doc/man3/CMS_add0_cert.pod b/doc/man3/CMS_add0_cert.pod index c9e793ca87495..1c280b718882c 100644 --- a/doc/man3/CMS_add0_cert.pod +++ b/doc/man3/CMS_add0_cert.pod @@ -22,10 +22,13 @@ CMS_add0_crl, CMS_add1_crl, CMS_get1_crls CMS_add0_cert() and CMS_add1_cert() add certificate I to I unless it is already present. -This can be used with L and L -to include a chain certificate or an extra signer certificate -and may be used with L to set a -fallback signer certificate or to help chain building in certificate validation. +Signer certificates and intermediate CA certificates are usually added +to a CMS structure by L and L, yet further +such certificates may be added in advance by directly calling these functions. +The verifier of the message can use the included certificates +as candidate signer certificates and for chain building. +These functions may also be used before calling L to add +fallback signer certificates or intermediate CA certificates for chain building. As the 0 implies, CMS_add0_cert() adds I internally to I and on success it must not be freed up by the caller. In contrast, the caller of CMS_add1_cert() must free I. diff --git a/doc/man3/CMS_verify.pod b/doc/man3/CMS_verify.pod index 744325569edb8..81cc44b3dab96 100644 --- a/doc/man3/CMS_verify.pod +++ b/doc/man3/CMS_verify.pod @@ -25,7 +25,7 @@ CMS_verify() is very similar to L. It verifies a B structure contained in a structure of type B. I points to the B structure to verify. The optional I parameter can provide a list of certificates, -which is searched first for the signer's certificate. +which is searched first for signer certificates. I may contain extra untrusted CA certificates that may be used for chain building as well as CRLs that may be used for certificate validation. I may be NULL or point to diff --git a/doc/man3/PKCS7_sign_add_signer.pod b/doc/man3/PKCS7_sign_add_signer.pod index 42c8f4ac86618..f55a0038b7972 100644 --- a/doc/man3/PKCS7_sign_add_signer.pod +++ b/doc/man3/PKCS7_sign_add_signer.pod @@ -34,8 +34,8 @@ PKCS7_add_certificate() adds to the B structure I the certificate I, which may be an end-entity (signer) certificate or a CA certificate useful for chain building. This is done internally by L and similar signing functions -but can also be called directly to add a further such certificate. -It may be used before calling L +but can also be called directly to add another such certificate. +It may be used also before calling L to provide any missing certificate(s) needed for chain building or to provide a fallback signer certificate. @@ -66,8 +66,8 @@ B structure will not be finalized so additional attributes can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is needed to finalize it. -If B is set the signer's certificate will not be included in the -B structure, the signer's certificate must still be supplied in the +If B is set, the signer certificates will not be included in the +B structure. The signer certificates must still be supplied in the I parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message. @@ -84,14 +84,12 @@ these algorithms is disabled then it will not be included. Certificates and CRLs are added to the I or I fields of PKCS7_SIGNED structure. -A certificate or CRL may be added to the same PKCS7 structure -more than once, although this does not make sense. =head1 RETURN VALUES PKCS7_sign_add_signers() returns an internal pointer to the B -structure just added, which can be used to set additional attributes -before it is finalized, or NULL if an error occurs. +structure just added (which can be used to set additional attributes +before it is finalized), or NULL if an error occurs. PKCS7_add_certificate() and PKCS7_add_crl() return 1 on success, 0 on error. diff --git a/doc/man3/PKCS7_verify.pod b/doc/man3/PKCS7_verify.pod index b1b08ed568e6e..4d1b230ac2977 100644 --- a/doc/man3/PKCS7_verify.pod +++ b/doc/man3/PKCS7_verify.pod @@ -18,7 +18,7 @@ PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure PKCS7_verify() is very similar to L. It verifies a PKCS#7 signedData structure given in I. The optional I parameter can provide a list of certificates, -which is searched first for the signer's certificate. +which is searched first for signer certificates. I may contain extra untrusted CA certificates that may be used for chain building as well as CRLs that may be used for certificate validation. I may be NULL or point to @@ -28,7 +28,7 @@ Otherwise I should be NULL, and then the signed data must be in I. The content is written to the BIO I unless it is NULL. I is an optional set of flags, which can be used to modify the operation. -PKCS7_get0_signers() retrieves the signer's certificates from I, it does +PKCS7_get0_signers() retrieves the signer certificates from I, it does B check their validity or whether any signatures are valid. The I and I parameters have the same meanings as in PKCS7_verify(). @@ -45,10 +45,10 @@ B. The default behavior allows this, for compatibility with older versions of OpenSSL. -An attempt is made to locate all the signer's certificates, first looking in +An attempt is made to locate all the signer certificates, first looking in the I parameter (if it is not NULL). Then they are looked up in any certificates contained in the I structure unless B is set. -If any signer's certificates cannot be located the operation fails. +If any signer certificates cannot be located the operation fails. Each signer certificate is chain verified using by default the C purpose and using the trusted certificate store I if supplied. @@ -71,8 +71,8 @@ parameter to change the default verify behaviour. Only the flag B is meaningful to PKCS7_get0_signers(). If B is set the certificates in the message itself are not -searched when locating the signer's certificates. -This means that all the signer's certificates must be in the I parameter. +searched when locating the signer certificates. +This means that all the signer certificates must be in the I parameter. If B is set and CRL checking is enabled in I then any CRLs in the message itself are ignored. @@ -81,7 +81,7 @@ If the B flag is set MIME headers for type C are deleted from the content. If the content is not of type C then an error is returned. -If B is set the signer's certificates are not chain verified. +If B is set the signer certificates are not chain verified. If B is set then the certificates contained in the message are not used as untrusted CA certificates for chain building. @@ -92,7 +92,7 @@ If B is set then the signatures on the data are not checked. One application of B is to only accept messages signed by a small number of certificates. The acceptable certificates would be passed -in the I parameter. In this case if the signer's certificate is not one +in the I parameter. In this case, if the signer's certificate is not one of the certificates supplied in I then the verify will fail because the signer cannot be found. @@ -117,7 +117,7 @@ The error can be obtained from L. =head1 BUGS -The trusted certificate store is not searched for the signer's certificates. +The trusted certificate store is not searched for the signer certificates. This is primarily due to the inadequacies of the current B functionality.