From: Dr. David von Oheimb <David.von.Oheimb@siemens.com>
Date: Sat, 3 Jun 2023 04:53:58 +0000 (+0200)
Subject: rename OSSL_CMP_get{,1}_caCerts and improve OSSL_CMP_exec_certreq.pod
X-Git-Tag: openssl-3.2.0-alpha1~412
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ec5a9cd11b92e75f097dbaa41c512f29cf8625e7;p=thirdparty%2Fopenssl.git

rename OSSL_CMP_get{,1}_caCerts and improve OSSL_CMP_exec_certreq.pod

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/apps/cmp.c b/apps/cmp.c
index 38f665ae74d..d56a5e451cb 100644
--- a/apps/cmp.c
+++ b/apps/cmp.c
@@ -2893,7 +2893,7 @@ static int do_genm(OSSL_CMP_CTX *ctx)
             return 0;
         }
 
-        if (!OSSL_CMP_get_caCerts(ctx, &cacerts))
+        if (!OSSL_CMP_get1_caCerts(ctx, &cacerts))
             return 0;
 
         /* could check authorization of sender/origin at this point */
diff --git a/crypto/cmp/cmp_genm.c b/crypto/cmp/cmp_genm.c
index f4be997eb20..2faeaf0d282 100644
--- a/crypto/cmp/cmp_genm.c
+++ b/crypto/cmp/cmp_genm.c
@@ -138,7 +138,7 @@ static OSSL_CMP_ITAV *get_genm_itav(OSSL_CMP_CTX *ctx,
     return NULL;
 }
 
-int OSSL_CMP_get_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out)
+int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out)
 {
     OSSL_CMP_ITAV *req, *itav;
     STACK_OF(X509) *certs = NULL;
diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod
index b13a5058b0b..0302c0471bd 100644
--- a/doc/man3/OSSL_CMP_exec_certreq.pod
+++ b/doc/man3/OSSL_CMP_exec_certreq.pod
@@ -14,7 +14,7 @@ OSSL_CMP_KUR,
 OSSL_CMP_try_certreq,
 OSSL_CMP_exec_RR_ses,
 OSSL_CMP_exec_GENM_ses,
-OSSL_CMP_get_caCerts
+OSSL_CMP_get1_caCerts
 - functions implementing CMP client transactions
 
 =head1 SYNOPSIS
@@ -34,8 +34,9 @@ OSSL_CMP_get_caCerts
  int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type,
                           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);
+ int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
 
 =head1 DESCRIPTION
 
@@ -114,19 +115,22 @@ typically return them as an indication that the certificate was already revoked.
 "rejection" is a clear error. The values "waiting" and "keyUpdateWarning"
 make no sense for revocation and thus are treated as an error as well.
 
-OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of
+OSSL_CMP_exec_GENM_ses() sends a genm general message containing the sequence of
 infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
 optionally provided in the I<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
 On success it records in I<ctx> the status B<OSSL_CMP_PKISTATUS_accepted>
-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.
+and returns the list of B<ITAV>s received in a genp response message.
+This can be used, for instance,
+with infoType C<signKeyPairTypes> to obtain the set of signature
+algorithm identifiers that the CA will certify for subject public keys.
 See RFC 4210 section 5.3.19 and appendix E.5 for details.
+Functions implementing more specific genm/genp exchanges are described next.
 
-OSSL_CMP_get_caCerts() uses a genm/gemp message exchange with infoType caCerts
+OSSL_CMP_get1_caCerts() uses a genm/genp 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.
+NULL output means that no CA certificates were provided by the server.
 
 =head1 NOTES
 
@@ -151,7 +155,7 @@ 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() and OSSL_CMP_get_caCerts()
+OSSL_CMP_exec_RR_ses() and OSSL_CMP_get1_caCerts()
 return 1 on success, 0 on error.
 
 OSSL_CMP_exec_GENM_ses() returns NULL on error,
@@ -175,7 +179,7 @@ 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.
+OSSL_CMP_get1_caCerts() was added in OpenSSL 3.2.
 
 =head1 COPYRIGHT
 
diff --git a/include/openssl/cmp.h.in b/include/openssl/cmp.h.in
index b072eb5b37e..0e49ee9d519 100644
--- a/include/openssl/cmp.h.in
+++ b/include/openssl/cmp.h.in
@@ -487,7 +487,7 @@ int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
 STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
 
 /* from cmp_genm.c */
-int OSSL_CMP_get_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
+int OSSL_CMP_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
 
 #  ifdef  __cplusplus
 }
diff --git a/util/libcrypto.num b/util/libcrypto.num
index de4c2b4fec6..24947c673f0 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -5447,7 +5447,7 @@ ASYNC_get_mem_functions                 ?	3_2_0	EXIST::FUNCTION:
 BIO_ADDR_dup                            ?	3_2_0	EXIST::FUNCTION:SOCK
 OSSL_CMP_ITAV_new_caCerts               ?	3_2_0	EXIST::FUNCTION:CMP
 OSSL_CMP_ITAV_get0_caCerts              ?	3_2_0	EXIST::FUNCTION:CMP
-OSSL_CMP_get_caCerts                    ?	3_2_0	EXIST::FUNCTION:CMP
+OSSL_CMP_get1_caCerts                   ?	3_2_0	EXIST::FUNCTION:CMP
 OSSL_CMP_CTX_get0_libctx                ?	3_2_0	EXIST::FUNCTION:CMP
 OSSL_CMP_CTX_get0_propq                 ?	3_2_0	EXIST::FUNCTION:CMP
 OSSL_CMP_CTX_reset_geninfo_ITAVs        ?	3_0_8	EXIST::FUNCTION:CMP