CMP doc: various small corrections, mostly on PBM vs. MAC-based prote…

…ction

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from #21138)

doc/man1/openssl-cmp.pod.in

@@ -659,11 +659,12 @@ is typically used when authenticating with pre-shared key (password-based MAC).
 
 =item B<-secret> I<arg>
 
-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 validating PBM-based protection of incoming messages.
-PBM stands for Password-Based Message Authentication Code.
+Provides the source of a secret value to use with MAC-based message protection.
 This takes precedence over the B<-cert> and B<-key> options.
+The secret is used for creating MAC-based protection of outgoing messages
+and for validating incoming messages that have MAC-based protection.
+The algorithm used by default is Password-Based Message Authentication Code (PBM)
+as defined in RFC 4210 section 5.1.3.1.
 
 For more information about the format of I<arg> see
 L<openssl-passphrase-options(1)>.
@@ -682,7 +683,8 @@ 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
 and as fallback issuer entry in the certificate template of IR/CR/KUR messages.
 
-When using signature-based message protection, this "protection certificate"
+When performing signature-based message protection,
+this "protection certificate", also called "signer certificate",
 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
@@ -713,8 +715,8 @@ have no effect on the certificate verification enabled via this option.
 
 The corresponding private key file for the client's current certificate given in
 the B<-cert> option.
-This will be used for signature-based message protection unless
-the B<-secret> option indicating PBM or B<-unprotected_requests> is given.
+This will be used for signature-based message protection unless the B<-secret>
+option indicating MAC-based protection or B<-unprotected_requests> is given.
 
 It is also used as a fallback for the B<-newkey> option with IR/CR/KUR messages.
 
@@ -730,15 +732,15 @@ L<openssl-passphrase-options(1)>.
 =item B<-digest> I<name>
 
 Specifies name of supported digest to use in RFC 4210's MSG_SIG_ALG
-and as the one-way function (OWF) in MSG_MAC_ALG.
+and as the one-way function (OWF) in C<MSG_MAC_ALG>.
 If applicable, this is used for message protection and
 proof-of-possession (POPO) signatures.
 To see the list of supported digests, use C<openssl list -digest-commands>.
 Defaults to C<sha256>.
 
 =item B<-mac> I<name>
 
-Specifies the name of the MAC algorithm in MSG_MAC_ALG.
+Specifies the name of the MAC algorithm in C<MSG_MAC_ALG>.
 To get the names of supported MAC algorithms use C<openssl list -mac-algorithms>
 and possibly combine such a name with the name of a supported digest algorithm,
 e.g., hmacWithSHA256.
@@ -1166,7 +1168,7 @@ In order to update the enrolled certificate one may call
 
   openssl cmp -section insta,kur
 
-using with PBM-based protection or
+using MAC-based protection with PBM or
 
   openssl cmp -section insta,kur,signature
 
@@ -1225,7 +1227,7 @@ Then it can start using the new cert and key.
     -newkey cl_key_new.pem -certout cl_cert.pem
   cp cl_key_new.pem cl_key.pem
 
-This command sequence can be repated as often as needed.
+This command sequence can be repeated as often as needed.
 
 =head2 Requesting information from CMP server
 

doc/man3/OSSL_CMP_CTX_new.pod

@@ -260,12 +260,12 @@ The following options can be set:
 
 =item B<OSSL_CMP_OPT_OWF_ALGNID>
         The NID of the digest algorithm to be used as one-way function (OWF)
-        in RFC 4210's MSG_MAC_ALG for PBM-based message protection.
+        for MAC-based message protection with password-based MAC (PBM).
+        See RFC 4210 section 5.1.3.1 for details.
         Default is SHA256.
 
 =item B<OSSL_CMP_OPT_MAC_ALGNID>
-        The NID of the MAC algorithm to be used in RFC 4210's MSG_MAC_ALG
-        for PBM-based message protection.
+        The NID of the MAC algorithm to be used for message protection with PBM.
         Default is HMAC-SHA1 as per RFC 4210.
 
 =item B<OSSL_CMP_OPT_REVOCATION_REASON>
@@ -450,8 +450,8 @@ The reference counts of those certificates handled successfully are increased.
 OSSL_CMP_CTX_get0_untrusted(OSSL_CMP_CTX *ctx) returns a pointer to the
 list of untrusted certs, which may be empty if unset.
 
-OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate
-related to the private key used for CMP message protection.
+OSSL_CMP_CTX_set1_cert() sets the CMP signer certificate, also called protection
+certificate, related to the private key for signature-based message protection.
 Therefore the public key of this I<cert> must correspond to
 the private key set before or thereafter via OSSL_CMP_CTX_set1_pkey().
 When using signature-based protection of CMP request messages
@@ -481,15 +481,15 @@ OSSL_CMP_CTX_set1_pkey() sets the client's private key corresponding to the
 CMP signer certificate set via OSSL_CMP_CTX_set1_cert().
 This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG)
 of outgoing messages
-unless a PBM secret has been set via OSSL_CMP_CTX_set1_secretValue().
+unless a symmetric secret has been set via OSSL_CMP_CTX_set1_secretValue().
 The I<pkey> argument may be NULL to clear the entry.
 
-OSSL_CMP_CTX_set1_secretValue() sets the byte string I<sec> with length I<len>
-as PBM secret in the given I<ctx> or clears it if the I<sec> argument is NULL.
-If present, this secret is used to create PBM-based protection of outgoing
-messages and to verify any PBM-based protection of incoming messages
-(protectionAlg = MSG_MAC_ALG). PBM stands for Password-Based MAC.
-PBM-based protection takes precedence over signature-based protection.
+OSSL_CMP_CTX_set1_secretValue() sets in I<ctx> the byte string I<sec> of length
+I<len> to use as pre-shared secret, or clears it if the I<sec> argument is NULL.
+If present, this secret is used to create MAC-based authentication and integrity
+protection (rather than applying signature-based protection)
+of outgoing messages and to verify authenticity and integrity of incoming
+messages that have MAC-based protection (protectionAlg = C<MSG_MAC_ALG>).
 
 OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue I<ref> with
 length I<len> in the given I<ctx> or clears it if the I<ref> argument is NULL.
@@ -500,7 +500,7 @@ then the sender field will contain the NULL-DN
 and the senderKID field of the CMP message header must be set.
 When signature-based protection is used the senderKID will be set to
 the subjectKeyIdentifier of the CMP signer certificate as far as present.
-If not present or when PBM-based protection is used
+If not present or when MAC-based protection is used
 the I<ref> value is taken as the fallback value for the senderKID.
 
 OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
@@ -731,7 +731,7 @@ Set up a CMP client context for sending requests and verifying responses:
     OSSL_CMP_CTX_set1_serverPath(cmp_ctx, path_or_alias);
     OSSL_CMP_CTX_set0_trustedStore(cmp_ctx, ts);
 
-Set up client credentials for password-based protection (PBM):
+Set up symmetric credentials for MAC-based message protection such as PBM:
 
     OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
     OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);

doc/man3/OSSL_CMP_exec_certreq.pod

@@ -42,7 +42,7 @@ client-server transactions, i.e., sequences of CMP requests and responses.
 
 All functions take a populated OSSL_CMP_CTX structure as their first argument.
 Usually the server name, port, and path ("CMP alias") need to be set, as well as
-credentials the client can use for authenticating itself to the client.
+credentials the client can use for authenticating itself to the server.
 In order to authenticate the server the client typically needs a trust store.
 The functions return their respective main results directly, while there are
 also accessor functions for retrieving various results and status information
@@ -72,7 +72,7 @@ and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>,
 L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc.
 For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead.
 The enrollment session may be blocked by sleeping until the addressed
-CA (or an intermedate PKI component) can fully process and answer the request.
+CA (or an intermediate PKI component) can fully process and answer the request.
 
 OSSL_CMP_try_certreq() is an alternative to the above functions that is
 more flexible regarding what to do after receiving a checkAfter value.
@@ -119,7 +119,7 @@ See RFC 4210 section 5.3.19 and appendix E.5 for details.
 
 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 
-So far the CMP client implementation is limited to one request per CMP message
+The CMP client implementation is limited to one request per CMP message
 (and consequently to at most one response component per CMP message).
 
 =head1 RETURN VALUES