Merging upstream version 4.23.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 56 insertions, 9 deletions

diff --git a/upstream/debian-unstable/man3/OSSL_CMP_exec_certreq.3ssl b/upstream/debian-unstable/man3/OSSL_CMP_exec_certreq.3ssl
index c778985b..e0150153 100644
--- a/upstream/debian-unstable/man3/OSSL_CMP_exec_certreq.3ssl
+++ b/upstream/debian-unstable/man3/OSSL_CMP_exec_certreq.3ssl
@@ -55,7 +55,7 @@
 .\" ========================================================================
 .\"
 .IX Title "OSSL_CMP_EXEC_CERTREQ 3SSL"
-.TH OSSL_CMP_EXEC_CERTREQ 3SSL 2024-02-03 3.1.5 OpenSSL
+.TH OSSL_CMP_EXEC_CERTREQ 3SSL 2024-04-04 3.2.2-dev OpenSSL
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -72,7 +72,9 @@ 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_get1_caCerts,
+OSSL_CMP_get1_rootCaKeyUpdate
 \&\- functions implementing CMP client transactions
 .SH SYNOPSIS
 .IX Header "SYNOPSIS"
@@ -92,7 +94,12 @@ OSSL_CMP_exec_GENM_ses
 \& 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);
 .Ve
 .SH DESCRIPTION
 .IX Header "DESCRIPTION"
@@ -158,7 +165,12 @@ a negative value as the \fIreq_type\fR argument then \fBOSSL_CMP_try_certreq()\f
 aborts the CMP transaction by sending an error message to the server.
 .PP
 \&\fBOSSL_CMP_exec_RR_ses()\fR requests the revocation of the certificate
-specified in the \fIctx\fR using \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3).
+specified in the \fIctx\fR using the issuer DN and serial number set by
+\&\fBOSSL_CMP_CTX_set1_issuer\fR\|(3) and \fBOSSL_CMP_CTX_set1_serialNumber\fR\|(3), respectively,
+otherwise the issuer DN and serial number
+of the certificate set by \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3),
+otherwise the subject DN and public key
+of the certificate signing request set by \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3).
 RFC 4210 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
@@ -166,13 +178,39 @@ 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.
 .PP
-\&\fBOSSL_CMP_exec_GENM_ses()\fR sends a general message containing the sequence of
+\&\fBOSSL_CMP_exec_GENM_ses()\fR sends a genm general message containing the sequence of
 infoType and infoValue pairs (InfoTypeAndValue; short: \fBITAV\fR)
 optionally provided in the \fIctx\fR using \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3).
 On success it records in \fIctx\fR the status \fBOSSL_CMP_PKISTATUS_accepted\fR
-and returns the list of \fBITAV\fRs received in the GENP message.
-This can be used, for instance, to poll for CRLs or CA Key Updates.
+and returns the list of \fBITAV\fRs received in a genp response message.
+This can be used, for instance,
+with infoType \f(CW\*(C`signKeyPairTypes\*(C'\fR 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.
+.PP
+\&\fBOSSL_CMP_get1_caCerts()\fR uses a genm/genp message exchange with infoType caCerts
+to obtain a list of CA certificates from the CMP server referenced by \fIctx\fR.
+On success it assigns to \fI*out\fR the list of certificates received,
+which must be freed by the caller.
+NULL output means that no CA certificates were provided by the server.
+.PP
+\&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR uses a genm request message
+with infoType rootCaCert to obtain from the CMP server referenced by \fIctx\fR
+in a genp response message with infoType rootCaKeyUpdate any update of the
+given root CA certificate \fIoldWithOld\fR and verifies it as far as possible.
+See RFC 4210 section 4.4 for details.
+On success it assigns to \fI*newWithNew\fR the root certificate received.
+When the \fInewWithOld\fR and \fIoldWithNew\fR 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.
+.PP
+\&\fBWARNING:\fR
+The \fInewWithNew\fR 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 \fIoldwithold\fR certificate if present, otherwise it cannot be stronger than
+the weakest trust in any of the certificates in the trust store of \fIctx\fR.
 .SH NOTES
 .IX Header "NOTES"
 CMP is defined in RFC 4210 (and CRMF in RFC 4211).
@@ -181,12 +219,16 @@ The CMP client implementation is limited to one request per CMP message
 (and consequently to at most one response component per CMP message).
 .PP
 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,
+trust, for instance via the caPubs field of a certificate response or using
+functions like \fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR,
 authentication of the CMP server is particularly critical.
 So special care must be taken setting up server authentication in \fIctx\fR
 using functions such as
-\&\fBOSSL_CMP_CTX_set0_trustedStore\fR\|(3) (for certificate-based authentication) or
+\&\fBOSSL_CMP_CTX_set0_trusted\fR\|(3) (for certificate-based authentication) or
 \&\fBOSSL_CMP_CTX_set1_secretValue\fR\|(3) (for MAC-based protection).
+If authentication is certificate-based, \fBOSSL_CMP_CTX_get0_validatedSrvCert\fR\|(3)
+should be used to obtain the server validated certificate
+and perform an authorization check based on it.
 .SH "RETURN VALUES"
 .IX Header "RETURN VALUES"
 \&\fBOSSL_CMP_exec_certreq()\fR, \fBOSSL_CMP_exec_IR_ses()\fR, \fBOSSL_CMP_exec_CR_ses()\fR,
@@ -203,7 +245,9 @@ In the latter case \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) yields NULL
 and the output parameter \fIcheckAfter\fR has been used to
 assign the received value unless \fIcheckAfter\fR is NULL.
 .PP
-\&\fBOSSL_CMP_exec_RR_ses()\fR returns 1 on success, 0 on error.
+\&\fBOSSL_CMP_exec_RR_ses()\fR, \fBOSSL_CMP_get1_caCerts()\fR,
+and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR
+return 1 on success, 0 on error.
 .PP
 \&\fBOSSL_CMP_exec_GENM_ses()\fR returns NULL on error,
 otherwise a pointer to the sequence of \fBITAV\fR received, which may be empty.
@@ -222,6 +266,9 @@ functions.
 .SH HISTORY
 .IX Header "HISTORY"
 The OpenSSL CMP support was added in OpenSSL 3.0.
+.PP
+\&\fBOSSL_CMP_get1_caCerts()\fR and \fBOSSL_CMP_get1_rootCaKeyUpdate()\fR
+were added in OpenSSL 3.2.
 .SH COPYRIGHT
 .IX Header "COPYRIGHT"
 Copyright 2007\-2023 The OpenSSL Project Authors. All Rights Reserved.