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 38f665ae74d20f21fa89e5869a067c9a23a2840e..d56a5e451cba0e0399aeeddaf38c272a5a420252 100644 (file)
--- 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 f4be997eb20f21e0025fdfc6acd0df67f3d3b79d..2faeaf0d282a6b63842b96cf8455861106162075 100644 (file)
--- 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 b13a5058b0b8b3a89a7962dd2916538bdea84b83..0302c0471bdc6894a1142c59cbf3f4674b694720 100644 (file)
--- 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 b072eb5b37ee5fa4e4164c46fa309197921dd212..0e49ee9d519ed2c6b8fd868a1afc6122bb1c7d64 100644 (file)
--- 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 de4c2b4fec61845787ca896288efc8c78bf0c9ca..24947c673f02a7f251b83325ac557e1203b3dab6 100644 (file)
--- 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