CMP app and API doc: add note on critical server auth on receiving trust anchor certs

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21129)

diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index b31162d266441b17c1a83b311c0f5266b04672bd..4d077175537cf6fa096f75ba71418525fd000a35 100644 (file)
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -1127,6 +1127,17 @@ only affect the certificate verification enabled via the B<-out_trusted> option.
 
 =head1 NOTES
 
+When a client obtains from a CMP server CA certificates that it is going to
+trust, for instance via the C<caPubs> field of a certificate response
+or using general messages with infoType C<caCerts>,
+authentication of the CMP server is particularly critical.
+So special care must be taken setting up server authentication
+using B<-trusted> and related options for certificate-based authentication
+or B<-secret> for MAC-based protection.
+If authentication is certificate-based, the B<-srvcertout> option
+should be used to obtain the validated server certificate
+and perform an authorization check based on it.
+
 When setting up CMP configurations and experimenting with enrollment options
 typically various errors occur until the configuration is correct and complete.
 When the CMP server reports an error the client will by default

diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod
index 71d21154fc909a8ae98a13db44d59599a1c558bd..fbf118c2b16ceab5af17034aacb61f66ff013750 100644 (file)
--- a/doc/man3/OSSL_CMP_exec_certreq.pod
+++ b/doc/man3/OSSL_CMP_exec_certreq.pod
@@ -139,6 +139,18 @@ CMP is defined in RFC 4210 (and CRMF in RFC 4211).
 The CMP client implementation is limited to one request per CMP message
 (and consequently to at most one response component per CMP message).
 
+When a client obtains from a CMP server CA certificates that it is going to
+trust, for instance via the caPubs field of a certificate response
+or using functions like OSSL_CMP_get1_caCerts(),
+authentication of the CMP server is particularly critical.
+So special care must be taken setting up server authentication in I<ctx>
+using functions such as
+L<OSSL_CMP_CTX_set0_trusted(3)> (for certificate-based authentication) or
+L<OSSL_CMP_CTX_set1_secretValue(3)> (for MAC-based protection).
+If authentication is certificate-based, L<OSSL_CMP_CTX_get0_validatedSrvCert(3)>
+should be used to obtain the server validated certificate
+and perform an authorization check based on it.
+
 =head1 RETURN VALUES
 
 OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(),