doc/man3/OSSL_CMP_exec_certreq.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 OSSL_CMP_exec_certreq,
 OSSL_CMP_exec_IR_ses,
 OSSL_CMP_exec_CR_ses,
 OSSL_CMP_exec_P10CR_ses,
 OSSL_CMP_exec_KUR_ses,
 OSSL_CMP_IR,
 OSSL_CMP_CR,
 OSSL_CMP_P10CR,
 OSSL_CMP_KUR,
 OSSL_CMP_try_certreq,
 OSSL_CMP_exec_RR_ses,
 OSSL_CMP_exec_GENM_ses,
 OSSL_CMP_get1_caCerts,
 OSSL_CMP_get1_rootCaKeyUpdate,
 OSSL_CMP_get1_crlUpdate,
 OSSL_CMP_get1_certReqTemplate
 - functions implementing CMP client transactions

 =head1 SYNOPSIS

  #include <openssl/cmp.h>

  X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type,
                              const OSSL_CRMF_MSG *crm);
  X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
  X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
  X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
  X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
  #define OSSL_CMP_IR
  #define OSSL_CMP_CR
  #define OSSL_CMP_P10CR
  #define OSSL_CMP_KUR
  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_get1_caCerts(OSSL_CMP_CTX *ctx, STACK_OF(X509) **out);
  int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx,
                                    const X509 *oldWithOld, X509 **newWithNew,
                                    X509 **newWithOld, X509 **oldWithNew);
  int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX *ctx, const X509 *crlcert,
                              const X509_CRL *last_crl,
                              X509_CRL **crl);
  int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx,
                                    OSSL_CRMF_CERTTEMPLATE **certTemplate,
                                    OSSL_CMP_ATAVS **keySpec);
 =head1 DESCRIPTION

 This is the OpenSSL API for doing CMP (Certificate Management Protocol)
 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 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
 from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.

 The default conveying protocol is HTTP.
 Timeout values may be given per request-response pair and per transaction.
 See L<OSSL_CMP_MSG_http_perform(3)> for details.

 OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI.

 OSSL_CMP_exec_CR_ses() requests an additional certificate.

 OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate.

 OSSL_CMP_exec_KUR_ses() obtains an updated certificate.

 These four types of certificate enrollment are implemented as macros
 calling OSSL_CMP_exec_certreq().

 OSSL_CMP_exec_certreq() performs a certificate request of the type specified
 by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR.
 For IR, CR, and KUR, the certificate template to be used in the request
 may be supplied via the I<crm> parameter pointing to a CRMF structure.
 Typically I<crm> is NULL, then the template ingredients are taken from I<ctx>
 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 (with polling and sleeping in between)
 until the server side can fully process and ultimately 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.
 When called for the first time (with no certificate request in progress for
 the given I<ctx>) it starts a new transaction by sending a certificate request
 constructed as stated above using the I<req_type> and optional I<crm> parameter.
 Otherwise (when according to I<ctx> a 'waiting' status has been received before)
 it continues polling for the pending request
 unless the I<req_type> argument is < 0, which aborts the request.
 If the requested certificate is available the function returns 1 and the
 caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate.
 If no error occurred but no certificate is available yet then
 OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried
 and returns -1 after assigning the received checkAfter value
 via the output pointer argument (unless it is NULL).
 The checkAfter value indicates the number of seconds the caller should let pass
 before trying again. The caller is free to sleep for the given number of seconds
 or for some other time and/or to do anything else before retrying by calling
 OSSL_CMP_try_certreq() again with the same parameter values as before.
 OSSL_CMP_try_certreq() then polls
 to see whether meanwhile the requested certificate is available.
 If the caller decides to abort the pending certificate request and provides
 a negative value as the I<req_type> argument then OSSL_CMP_try_certreq()
 aborts the CMP transaction by sending an error message to the server.

 OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
 specified in the I<ctx> using the issuer DN and serial number set by
 OSSL_CMP_CTX_set1_issuer(3) and OSSL_CMP_CTX_set1_serialNumber(3), respectively,
 otherwise the issuer DN and serial number
 of the certificate set by L<OSSL_CMP_CTX_set1_oldCert(3)>,
 otherwise the subject DN and public key
 of the certificate signing request set by L<OSSL_CMP_CTX_set1_p10CSR(3)>.
 RFC 9810 is vague in which PKIStatus should be returned by the server.
 We take "accepted" and "grantedWithMods" as clear success and handle
 "revocationWarning" and "revocationNotification" just as warnings because CAs
 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.
 The revocation session may be blocked (with polling and sleeping in between)
 until the server can fully process and ultimately answer the request.

 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)>.
 The message exchange may be blocked (with polling and sleeping in between)
 until the server can fully process and ultimately answer the request.
 On success the function records in I<ctx> status B<OSSL_CMP_PKISTATUS_accepted>
 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 9810 section 5.3.19 and appendix D.5 for details.
 Functions implementing more specific genm/genp exchanges are described next.

 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 output means that no CA certificates were provided by the server.

 OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message
 with infoType rootCaCert to obtain from the CMP server referenced by I<ctx>
 in a genp response message with infoType rootCaKeyUpdate any update of the
 given root CA certificate I<oldWithOld> and verifies it as far as possible.
 See RFC 9810 section 4.4 for details.
 On success it assigns to I<*newWithNew> the root certificate received.
 When the I<newWithOld> and I<oldWithNew> output parameters are not NULL,
 it assigns to them the corresponding transition certificates.
 NULL means that the respective certificate was not provided by the server.
 All certificates obtained this way must be freed by the caller.

 B<WARNING:>
 The I<newWithNew> certificate is meant to be a certificate that will be trusted.
 The trust placed in it cannot be stronger than the trust placed in
 the I<oldwithold> certificate if present, otherwise it cannot be stronger than
 the weakest trust in any of the certificates in the trust store of I<ctx>.

 OSSL_CMP_get1_crlUpdate() uses a genm request message with infoType crlStatusList
 to obtain CRL from the CMP server referenced by I<ctx> in a genp response message
 with infoType crls. It uses I<last_crl> and I<crlcert> to create
 a request with a status field as described for L<OSSL_CMP_CRLSTATUS_create(3)>.
 On success it assigns to I<*crl> the CRL received.
 NULL means that no CRL was provided by the server.
 The CRL obtained this way must be freed by the caller.

 OSSL_CMP_get1_certReqTemplate() uses a genm request message with
 infoType certReqTemplate to obtain a certificate request template from the
 CMP server referenced by I<ctx>. On success it assigns to I<*certTemplate>
 the certificate template received. NULL output means that no certificate
 request template was provided by the server.
 The optional I<keySpec> output parameter is assigned the key specification
 if received, otherwise it set to NULL.
 Both must be freed by the caller.

 =head1 NOTES

 CMP is defined in RFC 9810 (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() and OSSL_CMP_get1_rootCaKeyUpdate(),
 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(),
 OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
 pointer to the newly obtained X509 certificate on success, NULL on error.
 This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
 CSSL_CMP_CTX_reinit().

 OSSL_CMP_try_certreq() returns 1 if the requested certificate is available
 via L<OSSL_CMP_CTX_get0_newCert(3)>
 or on successfully aborting a pending certificate request, 0 on error, and -1
 in case a 'waiting' status has been received and checkAfter value is available.
 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(), OSSL_CMP_get1_caCerts(),
 OSSL_CMP_get1_rootCaKeyUpdate(), OSSL_CMP_get1_crlUpdate()
 and OSSL_CMP_get1_certReqTemplate()
 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.
 This pointer must be freed by the caller.

 =head1 EXAMPLES

 See OSSL_CMP_CTX for examples on how to prepare the context for these
 functions.

 =head1 SEE ALSO

 L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>,
 L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>,
 L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>,
 L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>,
 L<OSSL_CMP_MSG_http_perform(3)>, L<OSSL_CMP_CRLSTATUS_create(3)>

 =head1 HISTORY

 The OpenSSL CMP functions were added in OpenSSL 3.0.

 OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate()
 were added in OpenSSL 3.2.

 Support for delayed delivery of all types of response messages
 was added in OpenSSL 3.3.

 OSSL_CMP_get1_crlUpdate() and OSSL_CMP_get1_certReqTemplate()
 were added in OpenSSL 3.4.

 =head1 COPYRIGHT

 Copyright 2007-2025 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
	=pod

	=head1 NAME

	OSSL_CMP_exec_certreq,
	OSSL_CMP_exec_IR_ses,
	OSSL_CMP_exec_CR_ses,
	OSSL_CMP_exec_P10CR_ses,
	OSSL_CMP_exec_KUR_ses,
	OSSL_CMP_IR,
	OSSL_CMP_CR,
	OSSL_CMP_P10CR,
	OSSL_CMP_KUR,
	OSSL_CMP_try_certreq,
	OSSL_CMP_exec_RR_ses,
	OSSL_CMP_exec_GENM_ses,
	OSSL_CMP_get1_caCerts,
	OSSL_CMP_get1_rootCaKeyUpdate,
	OSSL_CMP_get1_crlUpdate,
	OSSL_CMP_get1_certReqTemplate
	- functions implementing CMP client transactions

	=head1 SYNOPSIS

	#include <openssl/cmp.h>

	X509 OSSL_CMP_exec_certreq(OSSL_CMP_CTX ctx, int req_type,
	const OSSL_CRMF_MSG *crm);
	X509 OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX ctx);
	X509 OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX ctx);
	X509 OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX ctx);
	X509 OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX ctx);
	#define OSSL_CMP_IR
	#define OSSL_CMP_CR
	#define OSSL_CMP_P10CR
	#define OSSL_CMP_KUR
	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_get1_caCerts(OSSL_CMP_CTX ctx, STACK_OF(X509) *out);
	int OSSL_CMP_get1_rootCaKeyUpdate(OSSL_CMP_CTX *ctx,
	const X509 oldWithOld, X509 *newWithNew,
	X509 newWithOld, X509 oldWithNew);
	int OSSL_CMP_get1_crlUpdate(OSSL_CMP_CTX ctx, const X509 crlcert,
	const X509_CRL *last_crl,
	X509_CRL **crl);
	int OSSL_CMP_get1_certReqTemplate(OSSL_CMP_CTX *ctx,
	OSSL_CRMF_CERTTEMPLATE **certTemplate,
	OSSL_CMP_ATAVS **keySpec);
	=head1 DESCRIPTION

	This is the OpenSSL API for doing CMP (Certificate Management Protocol)
	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 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
	from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.

	The default conveying protocol is HTTP.
	Timeout values may be given per request-response pair and per transaction.
	See L<OSSL_CMP_MSG_http_perform(3)> for details.

	OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI.

	OSSL_CMP_exec_CR_ses() requests an additional certificate.

	OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate.

	OSSL_CMP_exec_KUR_ses() obtains an updated certificate.

	These four types of certificate enrollment are implemented as macros
	calling OSSL_CMP_exec_certreq().

	OSSL_CMP_exec_certreq() performs a certificate request of the type specified
	by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR.
	For IR, CR, and KUR, the certificate template to be used in the request
	may be supplied via the I<crm> parameter pointing to a CRMF structure.
	Typically I<crm> is NULL, then the template ingredients are taken from I<ctx>
	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 (with polling and sleeping in between)
	until the server side can fully process and ultimately 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.
	When called for the first time (with no certificate request in progress for
	the given I<ctx>) it starts a new transaction by sending a certificate request
	constructed as stated above using the I<req_type> and optional I<crm> parameter.
	Otherwise (when according to I<ctx> a 'waiting' status has been received before)
	it continues polling for the pending request
	unless the I<req_type> argument is < 0, which aborts the request.
	If the requested certificate is available the function returns 1 and the
	caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate.
	If no error occurred but no certificate is available yet then
	OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried
	and returns -1 after assigning the received checkAfter value
	via the output pointer argument (unless it is NULL).
	The checkAfter value indicates the number of seconds the caller should let pass
	before trying again. The caller is free to sleep for the given number of seconds
	or for some other time and/or to do anything else before retrying by calling
	OSSL_CMP_try_certreq() again with the same parameter values as before.
	OSSL_CMP_try_certreq() then polls
	to see whether meanwhile the requested certificate is available.
	If the caller decides to abort the pending certificate request and provides
	a negative value as the I<req_type> argument then OSSL_CMP_try_certreq()
	aborts the CMP transaction by sending an error message to the server.

	OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
	specified in the I<ctx> using the issuer DN and serial number set by
	OSSL_CMP_CTX_set1_issuer(3) and OSSL_CMP_CTX_set1_serialNumber(3), respectively,
	otherwise the issuer DN and serial number
	of the certificate set by L<OSSL_CMP_CTX_set1_oldCert(3)>,
	otherwise the subject DN and public key
	of the certificate signing request set by L<OSSL_CMP_CTX_set1_p10CSR(3)>.
	RFC 9810 is vague in which PKIStatus should be returned by the server.
	We take "accepted" and "grantedWithMods" as clear success and handle
	"revocationWarning" and "revocationNotification" just as warnings because CAs
	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.
	The revocation session may be blocked (with polling and sleeping in between)
	until the server can fully process and ultimately answer the request.

	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)>.
	The message exchange may be blocked (with polling and sleeping in between)
	until the server can fully process and ultimately answer the request.
	On success the function records in I<ctx> status B<OSSL_CMP_PKISTATUS_accepted>
	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 9810 section 5.3.19 and appendix D.5 for details.
	Functions implementing more specific genm/genp exchanges are described next.

	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 output means that no CA certificates were provided by the server.

	OSSL_CMP_get1_rootCaKeyUpdate() uses a genm request message
	with infoType rootCaCert to obtain from the CMP server referenced by I<ctx>
	in a genp response message with infoType rootCaKeyUpdate any update of the
	given root CA certificate I<oldWithOld> and verifies it as far as possible.
	See RFC 9810 section 4.4 for details.
	On success it assigns to I<*newWithNew> the root certificate received.
	When the I<newWithOld> and I<oldWithNew> output parameters are not NULL,
	it assigns to them the corresponding transition certificates.
	NULL means that the respective certificate was not provided by the server.
	All certificates obtained this way must be freed by the caller.

	B<WARNING:>
	The I<newWithNew> certificate is meant to be a certificate that will be trusted.
	The trust placed in it cannot be stronger than the trust placed in
	the I<oldwithold> certificate if present, otherwise it cannot be stronger than
	the weakest trust in any of the certificates in the trust store of I<ctx>.

	OSSL_CMP_get1_crlUpdate() uses a genm request message with infoType crlStatusList
	to obtain CRL from the CMP server referenced by I<ctx> in a genp response message
	with infoType crls. It uses I<last_crl> and I<crlcert> to create
	a request with a status field as described for L<OSSL_CMP_CRLSTATUS_create(3)>.
	On success it assigns to I<*crl> the CRL received.
	NULL means that no CRL was provided by the server.
	The CRL obtained this way must be freed by the caller.

	OSSL_CMP_get1_certReqTemplate() uses a genm request message with
	infoType certReqTemplate to obtain a certificate request template from the
	CMP server referenced by I<ctx>. On success it assigns to I<*certTemplate>
	the certificate template received. NULL output means that no certificate
	request template was provided by the server.
	The optional I<keySpec> output parameter is assigned the key specification
	if received, otherwise it set to NULL.
	Both must be freed by the caller.

	=head1 NOTES

	CMP is defined in RFC 9810 (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() and OSSL_CMP_get1_rootCaKeyUpdate(),
	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(),
	OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
	pointer to the newly obtained X509 certificate on success, NULL on error.
	This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
	CSSL_CMP_CTX_reinit().

	OSSL_CMP_try_certreq() returns 1 if the requested certificate is available
	via L<OSSL_CMP_CTX_get0_newCert(3)>
	or on successfully aborting a pending certificate request, 0 on error, and -1
	in case a 'waiting' status has been received and checkAfter value is available.
	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(), OSSL_CMP_get1_caCerts(),
	OSSL_CMP_get1_rootCaKeyUpdate(), OSSL_CMP_get1_crlUpdate()
	and OSSL_CMP_get1_certReqTemplate()
	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.
	This pointer must be freed by the caller.

	=head1 EXAMPLES

	See OSSL_CMP_CTX for examples on how to prepare the context for these
	functions.

	=head1 SEE ALSO

	L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>,
	L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>,
	L<OSSL_CMP_CTX_set1_p10CSR(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>,
	L<OSSL_CMP_CTX_get0_newCert(3)>, L<OSSL_CMP_CTX_push0_genm_ITAV(3)>,
	L<OSSL_CMP_MSG_http_perform(3)>, L<OSSL_CMP_CRLSTATUS_create(3)>

	=head1 HISTORY

	The OpenSSL CMP functions were added in OpenSSL 3.0.

	OSSL_CMP_get1_caCerts() and OSSL_CMP_get1_rootCaKeyUpdate()
	were added in OpenSSL 3.2.

	Support for delayed delivery of all types of response messages
	was added in OpenSSL 3.3.

	OSSL_CMP_get1_crlUpdate() and OSSL_CMP_get1_certReqTemplate()
	were added in OpenSSL 3.4.

	=head1 COPYRIGHT

	Copyright 2007-2025 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