diff options
Diffstat (limited to 'static/freebsd/man3/OSSL_CMP_exec_certreq.3')
| -rw-r--r-- | static/freebsd/man3/OSSL_CMP_exec_certreq.3 | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/static/freebsd/man3/OSSL_CMP_exec_certreq.3 b/static/freebsd/man3/OSSL_CMP_exec_certreq.3 new file mode 100644 index 00000000..e4357894 --- /dev/null +++ b/static/freebsd/man3/OSSL_CMP_exec_certreq.3 @@ -0,0 +1,318 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OSSL_CMP_EXEC_CERTREQ 3ossl" +.TH OSSL_CMP_EXEC_CERTREQ 3ossl 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH 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 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #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 +.Ve +.PP +This is the OpenSSL API for doing CMP (Certificate Management Protocol) +client\-server transactions, i.e., sequences of CMP requests and responses. +.PP +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 \fIctx\fR. See \fBOSSL_CMP_CTX_new\fR\|(3) etc. for details. +.PP +The default conveying protocol is HTTP. +Timeout values may be given per request\-response pair and per transaction. +See \fBOSSL_CMP_MSG_http_perform\fR\|(3) for details. +.PP +\&\fBOSSL_CMP_exec_IR_ses()\fR requests an initial certificate from the given PKI. +.PP +\&\fBOSSL_CMP_exec_CR_ses()\fR requests an additional certificate. +.PP +\&\fBOSSL_CMP_exec_P10CR_ses()\fR conveys a legacy PKCS#10 CSR requesting a certificate. +.PP +\&\fBOSSL_CMP_exec_KUR_ses()\fR obtains an updated certificate. +.PP +These four types of certificate enrollment are implemented as macros +calling \fBOSSL_CMP_exec_certreq()\fR. +.PP +\&\fBOSSL_CMP_exec_certreq()\fR performs a certificate request of the type specified +by the \fIreq_type\fR 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 \fIcrm\fR parameter pointing to a CRMF structure. +Typically \fIcrm\fR is NULL, then the template ingredients are taken from \fIctx\fR +and need to be filled in using \fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), +\&\fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), etc. +For P10CR, \fBOSSL_CMP_CTX_set1_p10CSR\fR\|(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. +.PP +\&\fBOSSL_CMP_try_certreq()\fR 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 \fIctx\fR) it starts a new transaction by sending a certificate request +constructed as stated above using the \fIreq_type\fR and optional \fIcrm\fR parameter. +Otherwise (when according to \fIctx\fR a \*(Aqwaiting\*(Aq status has been received before) +it continues polling for the pending request +unless the \fIreq_type\fR argument is < 0, which aborts the request. +If the requested certificate is available the function returns 1 and the +caller can use \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) to retrieve the new certificate. +If no error occurred but no certificate is available yet then +\&\fBOSSL_CMP_try_certreq()\fR 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 +\&\fBOSSL_CMP_try_certreq()\fR again with the same parameter values as before. +\&\fBOSSL_CMP_try_certreq()\fR 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 \fIreq_type\fR argument then \fBOSSL_CMP_try_certreq()\fR +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 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 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. +.PP +\&\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). +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 \fIctx\fR status \fBOSSL_CMP_PKISTATUS_accepted\fR +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 9810 section 5.3.19 and appendix D.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 9810 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. +.PP +\&\fBOSSL_CMP_get1_crlUpdate()\fR uses a genm request message with infoType crlStatusList +to obtain CRL from the CMP server referenced by \fIctx\fR in a genp response message +with infoType crls. It uses \fIlast_crl\fR and \fIcrlcert\fR to create +a request with a status field as described for \fBOSSL_CMP_CRLSTATUS_create\fR\|(3). +On success it assigns to \fI*crl\fR the CRL received. +NULL means that no CRL was provided by the server. +The CRL obtained this way must be freed by the caller. +.PP +\&\fBOSSL_CMP_get1_certReqTemplate()\fR uses a genm request message with +infoType certReqTemplate to obtain a certificate request template from the +CMP server referenced by \fIctx\fR. On success it assigns to \fI*certTemplate\fR +the certificate template received. NULL output means that no certificate +request template was provided by the server. +The optional \fIkeySpec\fR output parameter is assigned the key specification +if received, otherwise it set to NULL. +Both must be freed by the caller. +.SH NOTES +.IX Header "NOTES" +CMP is defined in RFC 9810 (and CRMF in RFC 4211). +.PP +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 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_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, +\&\fBOSSL_CMP_exec_P10CR_ses()\fR, and \fBOSSL_CMP_exec_KUR_ses()\fR return a +pointer to the newly obtained X509 certificate on success, NULL on error. +This pointer will be freed implicitly by \fBOSSL_CMP_CTX_free()\fR or +\&\fBCSSL_CMP_CTX_reinit()\fR. +.PP +\&\fBOSSL_CMP_try_certreq()\fR returns 1 if the requested certificate is available +via \fBOSSL_CMP_CTX_get0_newCert\fR\|(3) +or on successfully aborting a pending certificate request, 0 on error, and \-1 +in case a \*(Aqwaiting\*(Aq status has been received and checkAfter value is available. +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, \fBOSSL_CMP_get1_caCerts()\fR, +\&\fBOSSL_CMP_get1_rootCaKeyUpdate()\fR, \fBOSSL_CMP_get1_crlUpdate()\fR +and \fBOSSL_CMP_get1_certReqTemplate()\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. +This pointer must be freed by the caller. +.SH EXAMPLES +.IX Header "EXAMPLES" +See OSSL_CMP_CTX for examples on how to prepare the context for these +functions. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBOSSL_CMP_CTX_new\fR\|(3), \fBOSSL_CMP_CTX_free\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_subjectName\fR\|(3), \fBOSSL_CMP_CTX_set0_newPkey\fR\|(3), +\&\fBOSSL_CMP_CTX_set1_p10CSR\fR\|(3), \fBOSSL_CMP_CTX_set1_oldCert\fR\|(3), +\&\fBOSSL_CMP_CTX_get0_newCert\fR\|(3), \fBOSSL_CMP_CTX_push0_genm_ITAV\fR\|(3), +\&\fBOSSL_CMP_MSG_http_perform\fR\|(3), \fBOSSL_CMP_CRLSTATUS_create\fR\|(3) +.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. +.PP +Support for delayed delivery of all types of response messages +was added in OpenSSL 3.3. +.PP +\&\fBOSSL_CMP_get1_crlUpdate()\fR and \fBOSSL_CMP_get1_certReqTemplate()\fR +were added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2007\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |