minor doc fixes for CMP and HTTP

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26924)

apps/openssl-vms.cnf

@@ -342,8 +342,8 @@ path = pkix/
 
 # Server authentication
 recipient = "/C=FI/O=Insta Demo/CN=Insta Demo CA" # or set srvcert or issuer
-ignore_keyusage = 1 # potentially needed quirk
+ignore_keyusage = 1 # quirk needed to accept Insta CA cert not including digitalsignature
-unprotected_errors = 1 # potentially needed quirk
+unprotected_errors = 1 # quirk needed to accept negative responses possibly not protected
 extracertsout = insta.extracerts.pem
 
 # Client authentication

apps/openssl.cnf

@@ -342,8 +342,8 @@ path = pkix/
 
 # Server authentication
 recipient = "/C=FI/O=Insta Demo/CN=Insta Demo CA" # or set srvcert or issuer
-ignore_keyusage = 1 # potentially needed quirk
+ignore_keyusage = 1 # quirk needed to accept Insta CA cert not including digitalsignature
-unprotected_errors = 1 # potentially needed quirk
+unprotected_errors = 1 # quirk needed to accept negative responses possibly not protected
 extracertsout = insta.extracerts.pem
 
 # Client authentication

doc/man1/openssl-cmp.pod.in

@@ -258,7 +258,7 @@ ITAV B<infoType>s is printed to stdout.
 
 Set InfoType name to use for requesting specific info in B<genm>,
 e.g., C<signKeyPairTypes>.
-There is specific support for C<caCerts>, C<rootCaCert>,  
+There is specific support for C<caCerts>, C<rootCaCert>,
 C<certReqTemplate>, and C<crlStatusList> (CRL update retrieval).
 
 =item B<-profile> I<name>
@@ -480,7 +480,7 @@ if neither B<-recipient>, B<-srvcert>, nor B<-issuer> is given.
 
 =item B<-issuer> I<name>
 
-X.509 Distinguished Name (DN) use as issuer field
+X.509 Distinguished Name (DN) to place as the issuer field
 in the requested certificate template in IR/CR/KUR/RR messages.
 If the NULL-DN (C</>) is given then no issuer is placed in the template.
 
@@ -777,20 +777,21 @@ If on success no such cert was received, this is indicated by deleting the file.
 
 =item B<-crlcert> I<filename>
 
-Certificate used for specifying a CRL issuer when requesting a CRL 
+Certificate to derive CRL issuer data for the source field
-in a genm message with infoType C<crlStatusList>.
+when obtaining a CRL in a genm request with infoType C<crlStatusList>.
 Any available distribution point name is preferred over issuer names.
 
 =item B<-oldcrl> I<filename>
 
-CRL used for specifying a CRL issuer when requesting a CRL 
+The CRL to obtain an update for in a genm request with infoType C<crlStatusList>.
-in a genm message with infoType C<crlStatusList>.
+Unless the B<-crlcert> option is provided as well,
+the given CRL is used for deriving CRL issuer data for the source field.
 Any available distribution point name is preferred over issuer names.
-If also B<-crlcrt> is given, its data is preferred over data from B<-oldcrl>.
+If the CRL contains a thisUpdate field, its value is copied to the request.
 
 =item B<-crlout> I<filename>
 
-The file to save CRL received in a genp message of infoType C<crls>.
+The file to save any CRL received in a genp message of infoType C<crls>.
 If on success no such CRL was received, this is indicated by deleting the file.
 
 =back
@@ -1395,13 +1396,10 @@ or by referencing in addition the B<[cr]> section of the example configuration:
 
 In order to update the enrolled certificate one may call
 
-  openssl cmp -section insta,kur
-
-using MAC-based protection with PBM or
-
   openssl cmp -section insta,kur,signature
 
-using signature-based protection.
+using signature-based protection with the certificate that is to be updated.
+For certificate updates, MAC-based protection should generally not be used.
 
 In a similar way any previously enrolled certificate may be revoked by
 

doc/man3/OSSL_CMP_ITAV_new_caCerts.pod

@@ -108,27 +108,6 @@ Data from I<cert>, if present, is preferred over data from I<crl>.
 If no distribution point names are available,
 candidate issuer names are taken from following sources, as far as present:
 
-OSSL_CMP_ITAV_new0_certReqTemplate() creates an B<OSSL_CMP_ITAV> structure
-of type B<certReqTemplate>.
-If I<certTemplate> is NULL then also I<keySpec> must be NULL,
-and the resulting ITAV can be used in a B<genm> message to obtain the
-requirements a PKI has on the certificate template used to request certificates,
-or in a B<genp> message stating that there are no such requirements.
-Otherwise the resulting ITAV includes a CertReqTemplateValue structure
-with I<certTemplate> of type B<OSSL_CRMF_CERTTEMPLATE> and an optional list
-of key specifications I<keySpec>, each being of type B<OSSL_CMP_ATAV>, and
-the resulting ATAV can be used in a B<genp> message to provide requirements.
-
-OSSL_CMP_ITAV_get1_certReqTemplate()
-requires that I<itav> has type B<certReqTemplate>.
-If assigns NULL to I<*certTemplate> if no B<OSSL_CRMF_CERTTEMPLATE> structure
-with a certificate template value is in I<itav>,
-otherwise a copy of the certTemplate field value.
-If I<keySpec> is not NULL, it is assigned NULL
-if the structure is not present in I<itav> or the keySpec field is absent.
-Otherwise, the function checks that all elements of keySpec field are of type
-B<algId> or B<rsaKeyLen> and assigns to I<*keySpec> a copy of the keySpec field.
-
 =over 4
 
 =item the list of distribution points in the first cRLDistributionPoints
@@ -171,6 +150,27 @@ the list of CRLs contained in the infoValue field of I<itav>.
 The pointer may be NULL if no CRL is included.
 It is an error if the infoType of I<itav> is not B<crls>.
 
+OSSL_CMP_ITAV_new0_certReqTemplate() creates an B<OSSL_CMP_ITAV> structure
+of type B<certReqTemplate>.
+If I<certTemplate> is NULL then also I<keySpec> must be NULL,
+and the resulting ITAV can be used in a B<genm> message to obtain the
+requirements a PKI has on the certificate template used to request certificates,
+or in a B<genp> message stating that there are no such requirements.
+Otherwise the resulting ITAV includes a CertReqTemplateValue structure
+with I<certTemplate> of type B<OSSL_CRMF_CERTTEMPLATE> and an optional list
+of key specifications I<keySpec>, each being of type B<OSSL_CMP_ATAV>, and
+the resulting ATAV can be used in a B<genp> message to provide requirements.
+
+OSSL_CMP_ITAV_get1_certReqTemplate()
+requires that I<itav> has type B<certReqTemplate>.
+If assigns NULL to I<*certTemplate> if no B<OSSL_CRMF_CERTTEMPLATE> structure
+with a certificate template value is in I<itav>,
+otherwise a copy of the certTemplate field value.
+If I<keySpec> is not NULL, it is assigned NULL
+if the structure is not present in I<itav> or the keySpec field is absent.
+Otherwise, the function checks that all elements of keySpec field are of type
+B<algId> or B<rsaKeyLen> and assigns to I<*keySpec> a copy of the keySpec field.
+
 =head1 NOTES
 
 CMP is defined in RFC 4210.

doc/man3/OSSL_HTTP_transfer.pod

@@ -62,6 +62,7 @@ for connecting to the given server and the optionally given I<port>,
 defaulting to 80 for HTTP or 443 for HTTPS.
 Then this internal BIO is used for setting up a connection
 and for exchanging one or more request and response.
+
 If I<bio> is given and I<rbio> is NULL then this I<bio> is used instead.
 If both I<bio> and I<rbio> are given (which may be memory BIOs for instance)
 then no explicit connection is set up, but
@@ -69,7 +70,8 @@ I<bio> is used for writing requests and I<rbio> for reading responses.
 As soon as the client has flushed I<bio> the server must be ready to provide
 a response or indicate a waiting condition via I<rbio>.
 
-If I<bio> is given, it is an error to provide I<proxy> or I<no_proxy> arguments,
+If I<bio> is given,
+it is an error to provide non-NULL I<proxy> or I<no_proxy> arguments,
 while I<server> and I<port> arguments may be given to support diagnostic output.
 If I<bio> is NULL the optional I<proxy> parameter can be used to set an
 HTTP(S) proxy to use (unless overridden by "no_proxy" settings).