CMP: add support for genm/genp messages with id-it-caCerts

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/19231)

5 files changed, 85 insertions, 6 deletions

diff --git a/doc/build.info b/doc/build.info
index 52db908985..6031a85d4d 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -1591,6 +1591,10 @@ DEPEND[html/man3/OSSL_CMP_HDR_get0_transactionID.html]=man3/OSSL_CMP_HDR_get0_tr
 GENERATE[html/man3/OSSL_CMP_HDR_get0_transactionID.html]=man3/OSSL_CMP_HDR_get0_transactionID.pod
 DEPEND[man/man3/OSSL_CMP_HDR_get0_transactionID.3]=man3/OSSL_CMP_HDR_get0_transactionID.pod
 GENERATE[man/man3/OSSL_CMP_HDR_get0_transactionID.3]=man3/OSSL_CMP_HDR_get0_transactionID.pod
+DEPEND[html/man3/OSSL_CMP_ITAV_new_caCerts.html]=man3/OSSL_CMP_ITAV_new_caCerts.pod
+GENERATE[html/man3/OSSL_CMP_ITAV_new_caCerts.html]=man3/OSSL_CMP_ITAV_new_caCerts.pod
+DEPEND[man/man3/OSSL_CMP_ITAV_new_caCerts.3]=man3/OSSL_CMP_ITAV_new_caCerts.pod
+GENERATE[man/man3/OSSL_CMP_ITAV_new_caCerts.3]=man3/OSSL_CMP_ITAV_new_caCerts.pod
 DEPEND[html/man3/OSSL_CMP_ITAV_set0.html]=man3/OSSL_CMP_ITAV_set0.pod
 GENERATE[html/man3/OSSL_CMP_ITAV_set0.html]=man3/OSSL_CMP_ITAV_set0.pod
 DEPEND[man/man3/OSSL_CMP_ITAV_set0.3]=man3/OSSL_CMP_ITAV_set0.pod
@@ -3289,6 +3293,7 @@ html/man3/OSSL_ALGORITHM.html \
 html/man3/OSSL_CALLBACK.html \
 html/man3/OSSL_CMP_CTX_new.html \
 html/man3/OSSL_CMP_HDR_get0_transactionID.html \
+html/man3/OSSL_CMP_ITAV_new_caCerts.html \
 html/man3/OSSL_CMP_ITAV_set0.html \
 html/man3/OSSL_CMP_MSG_get0_header.html \
 html/man3/OSSL_CMP_MSG_http_perform.html \
@@ -3924,6 +3929,7 @@ man/man3/OSSL_ALGORITHM.3 \
 man/man3/OSSL_CALLBACK.3 \
 man/man3/OSSL_CMP_CTX_new.3 \
 man/man3/OSSL_CMP_HDR_get0_transactionID.3 \
+man/man3/OSSL_CMP_ITAV_new_caCerts.3 \
 man/man3/OSSL_CMP_ITAV_set0.3 \
 man/man3/OSSL_CMP_MSG_get0_header.3 \
 man/man3/OSSL_CMP_MSG_http_perform.3 \
diff --git a/doc/internal/man3/ossl_cmp_mock_srv_new.pod b/doc/internal/man3/ossl_cmp_mock_srv_new.pod
index 119077ea7c..59568c65fc 100644
--- a/doc/internal/man3/ossl_cmp_mock_srv_new.pod
+++ b/doc/internal/man3/ossl_cmp_mock_srv_new.pod
@@ -45,16 +45,17 @@ ossl_cmp_mock_srv_set1_refCert() sets the reference certificate to be expected
 for rr messages and for any oldCertID included in kur messages.
 
 ossl_cmp_mock_srv_set1_certOut() sets the certificate to be returned in
-cp/ip/kup.
+cp/ip/kup messages.
 Note that on each certificate request the mock server does not produce
 a fresh certificate but just returns the same pre-existing certificate.
 
 ossl_cmp_mock_srv_set1_chainOut() sets the certificate chain to be added to
-the extraCerts in a cp/ip/kup.
+the extraCerts in a cp/ip/kup message.
 It should be useful for the validation of the certificate given via
 ossl_cmp_mock_srv_set1_certOut().
 
-ossl_cmp_mock_srv_set1_caPubsOut() sets the caPubs to be returned in an ip.
+ossl_cmp_mock_srv_set1_caPubsOut() sets the caPubs to be returned in an ip msg
+and the list of certificates to be returned in a genp of infoType caCerts.
 
 ossl_cmp_mock_srv_set_statusInfo() sets the status info to be returned.
 
diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in
index 76c4313bd5..2c8a8b2540 100644
--- a/doc/man1/openssl-cmp.pod.in
+++ b/doc/man1/openssl-cmp.pod.in
@@ -236,6 +236,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>.
+So far, there is specific support for C<caCerts>.
 
 =item B<-geninfo> I<OID:int:N>
 
@@ -655,7 +656,8 @@ field of the last received response message that is not a pollRep nor PKIConf.
 =item B<-cacertsout> I<filename>
 
 The file where to save the list of CA certificates contained in the caPubs field
-if a positive certificate response (i.e., IP, CP, or KUP) message was received.
+if a positive certificate response (i.e., IP, CP, or KUP) message was received
+or contained in a general response (genp) message with infoType C<caCerts>.
 
 =back
 
diff --git a/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod
new file mode 100644
index 0000000000..eb397388aa
--- /dev/null
+++ b/doc/man3/OSSL_CMP_ITAV_new_caCerts.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+OSSL_CMP_ITAV_new_caCerts,
+OSSL_CMP_ITAV_get0_caCerts
+- CMP utility functions for handling specific genm and genp messages
+
+=head1 SYNOPSIS
+
+ #include <openssl/cmp.h>
+
+ OSSL_CMP_ITAV *OSSL_CMP_ITAV_new_caCerts(const STACK_OF(X509) *caCerts);
+ int OSSL_CMP_ITAV_get0_caCerts(const OSSL_CMP_ITAV *itav, STACK_OF(X509) **out);
+
+=head1 DESCRIPTION
+
+ITAV is short for InfoTypeAndValue.
+
+OSSL_CMP_ITAV_new_caCerts() creates an B<OSSL_CMP_ITAV> structure of type
+B<caCerts> and fills it with a copy of the provided list of certificates.
+The I<caCerts> argument may be NULL or contain any number of certificates.
+
+OSSL_CMP_ITAV_get0_caCerts() requires that I<itav> has type B<caCerts>.
+It assigns NULL to I<*out> if there are no CA certificates in I<itav>, otherwise
+the internal pointer of type B<STACK_OF(X509)> with the certificates present.
+
+=head1 NOTES
+
+CMP is defined in RFC 4210.
+
+=head1 RETURN VALUES
+
+OSSL_CMP_ITAV_new_caCerts()
+returns a pointer to the new ITAV structure on success, or NULL on error.
+
+OSSL_CMP_ITAV_get0_caCerts()
+returns 1 on success, 0 on error.
+
+=head1 SEE ALSO
+
+L<OSSL_CMP_ITAV_create(3)> and L<OSSL_CMP_ITAV_get0_type(3)>
+
+=head1 HISTORY
+
+OSSL_CMP_ITAV_new_caCerts() and
+OSSL_CMP_ITAV_get0_rootCaCert()
+were added in OpenSSL 3.2.
+
+=head1 COPYRIGHT
+
+Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod
index b0d81c7c41..a418657e3c 100644
--- a/doc/man3/OSSL_CMP_exec_certreq.pod
+++ b/doc/man3/OSSL_CMP_exec_certreq.pod
@@ -13,7 +13,8 @@ OSSL_CMP_P10CR,
 OSSL_CMP_KUR,
 OSSL_CMP_try_certreq,
 OSSL_CMP_exec_RR_ses,
-OSSL_CMP_exec_GENM_ses
+OSSL_CMP_exec_GENM_ses,
+OSSL_CMP_get_caCerts
 - functions implementing CMP client transactions
 
 =head1 SYNOPSIS
@@ -34,6 +35,7 @@ OSSL_CMP_exec_GENM_ses
                           const OSSL_CRMF_MSG *crm, int *checkAfter);
  int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
  STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
+ int OSSL_CMP_get_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
 
 =head1 DESCRIPTION
 
@@ -115,6 +117,12 @@ and returns the list of B<ITAV>s received in the GENP message.
 This can be used, for instance, to poll for CRLs or CA Key Updates.
 See RFC 4210 section 5.3.19 and appendix E.5 for details.
 
+OSSL_CMP_get_caCerts() uses a genm/gemp message exchange with infoType caCerts
+to obtain a list of CA certificates from the CMP server referenced by I<ctx>.
+On success it assigns to I<*out> the list of certificates received,
+which must be freed by the caller.
+NULL means that no CA certificate is available at the server.
+
 =head1 NOTES
 
 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
@@ -138,7 +146,8 @@ In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL
 and the output parameter I<checkAfter> has been used to
 assign the received value unless I<checkAfter> is NULL.
 
-OSSL_CMP_exec_RR_ses() returns 1 on success, 0 on error.
+OSSL_CMP_exec_RR_ses() and OSSL_CMP_get_caCerts()
+return 1 on success, 0 on error.
 
 OSSL_CMP_exec_GENM_ses() returns NULL on error,
 otherwise a pointer to the sequence of B<ITAV> received, which may be empty.
@@ -161,6 +170,8 @@ L<OSSL_CMP_MSG_http_perform(3)>
 
 The OpenSSL CMP support was added in OpenSSL 3.0.
 
+OSSL_CMP_get_caCerts() was added in OpenSSL 3.2.
+
 =head1 COPYRIGHT
 
 Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.