1OSSL_CMP_EXEC_CERTREQ(3ossl)        OpenSSL       OSSL_CMP_EXEC_CERTREQ(3ossl)
2
3
4

NAME

6       OSSL_CMP_exec_certreq, OSSL_CMP_exec_IR_ses, OSSL_CMP_exec_CR_ses,
7       OSSL_CMP_exec_P10CR_ses, OSSL_CMP_exec_KUR_ses, OSSL_CMP_IR,
8       OSSL_CMP_CR, OSSL_CMP_P10CR, OSSL_CMP_KUR, OSSL_CMP_try_certreq,
9       OSSL_CMP_exec_RR_ses, OSSL_CMP_exec_GENM_ses - functions implementing
10       CMP client transactions
11

SYNOPSIS

13        #include <openssl/cmp.h>
14
15        X509 *OSSL_CMP_exec_certreq(OSSL_CMP_CTX *ctx, int req_type,
16                                    const OSSL_CRMF_MSG *crm);
17        X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
18        X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
19        X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
20        X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
21        #define OSSL_CMP_IR
22        #define OSSL_CMP_CR
23        #define OSSL_CMP_P10CR
24        #define OSSL_CMP_KUR
25        int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type,
26                                 const OSSL_CRMF_MSG *crm, int *checkAfter);
27        int OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
28        STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
29

DESCRIPTION

31       This is the OpenSSL API for doing CMP (Certificate Management Protocol)
32       client-server transactions, i.e., sequences of CMP requests and
33       responses.
34
35       All functions take a populated OSSL_CMP_CTX structure as their first
36       argument.  Usually the server name, port, and path ("CMP alias") need
37       to be set, as well as credentials the client can use for authenticating
38       itself to the client.  In order to authenticate the server the client
39       typically needs a trust store.  The functions return their respective
40       main results directly, while there are also accessor functions for
41       retrieving various results and status information from the ctx. See
42       OSSL_CMP_CTX_new(3) etc. for details.
43
44       The default conveying protocol is HTTP.  Timeout values may be given
45       per request-response pair and per transaction.  See
46       OSSL_CMP_MSG_http_perform(3) for details.
47
48       OSSL_CMP_exec_IR_ses() requests an initial certificate from the given
49       PKI.
50
51       OSSL_CMP_exec_CR_ses() requests an additional certificate.
52
53       OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a
54       certificate.
55
56       OSSL_CMP_exec_KUR_ses() obtains an updated certificate.
57
58       These four types of certificate enrollment are implemented as macros
59       calling OSSL_CMP_exec_certreq().
60
61       OSSL_CMP_exec_certreq() performs a certificate request of the type
62       specified by the req_type parameter, which may be IR, CR, P10CR, or
63       KUR.  For IR, CR, and KUR, the certificate template to be used in the
64       request may be supplied via the crm parameter pointing to a CRMF
65       structure.  Typically crm is NULL, then the template ingredients are
66       taken from ctx and need to be filled in using
67       OSSL_CMP_CTX_set1_subjectName(3), OSSL_CMP_CTX_set0_newPkey(3),
68       OSSL_CMP_CTX_set1_oldCert(3), etc.  For P10CR,
69       OSSL_CMP_CTX_set1_p10CSR(3) needs to be used instead.  The enrollment
70       session may be blocked by sleeping until the addressed CA (or an
71       intermedate PKI component) can fully process and answer the request.
72
73       OSSL_CMP_try_certreq() is an alternative to the above functions that is
74       more flexible regarding what to do after receiving a checkAfter value.
75       When called for the first time (with no certificate request in progress
76       for the given ctx) it starts a new transaction by sending a certificate
77       request constructed as stated above using the req_type and optional crm
78       parameter.  Otherwise (when according to ctx a 'waiting' status has
79       been received before) it continues polling for the pending request
80       unless the req_type argument is < 0, which aborts the request.  If the
81       requested certificate is available the function returns 1 and the
82       caller can use OSSL_CMP_CTX_get0_newCert(3) to retrieve the new
83       certificate.  If no error occurred but no certificate is available yet
84       then OSSL_CMP_try_certreq() remembers in the CMP context that it should
85       be retried and returns -1 after assigning the received checkAfter value
86       via the output pointer argument (unless it is NULL).  The checkAfter
87       value indicates the number of seconds the caller should let pass before
88       trying again. The caller is free to sleep for the given number of
89       seconds or for some other time and/or to do anything else before
90       retrying by calling OSSL_CMP_try_certreq() again with the same
91       parameter values as before.  OSSL_CMP_try_certreq() then polls to see
92       whether meanwhile the requested certificate is available.  If the
93       caller decides to abort the pending certificate request and provides a
94       negative value as the req_type argument then OSSL_CMP_try_certreq()
95       aborts the CMP transaction by sending an error message to the server.
96
97       OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
98       specified in the ctx using OSSL_CMP_CTX_set1_oldCert(3).  RFC 4210 is
99       vague in which PKIStatus should be returned by the server.  We take
100       "accepted" and "grantedWithMods" as clear success and handle
101       "revocationWarning" and "revocationNotification" just as warnings
102       because CAs typically return them as an indication that the certificate
103       was already revoked.  "rejection" is a clear error. The values
104       "waiting" and "keyUpdateWarning" make no sense for revocation and thus
105       are treated as an error as well.
106
107       OSSL_CMP_exec_GENM_ses() sends a general message containing the
108       sequence of infoType and infoValue pairs (InfoTypeAndValue; short:
109       ITAV) optionally provided in the ctx using
110       OSSL_CMP_CTX_push0_genm_ITAV(3).  On success it records in ctx the
111       status OSSL_CMP_PKISTATUS_accepted and returns the list of ITAVs
112       received in the GENP message.  This can be used, for instance, to poll
113       for CRLs or CA Key Updates.  See RFC 4210 section 5.3.19 and appendix
114       E.5 for details.
115

NOTES

117       CMP is defined in RFC 4210 (and CRMF in RFC 4211).
118
119       So far the CMP client implementation is limited to one request per CMP
120       message (and consequently to at most one response component per CMP
121       message).
122

RETURN VALUES

124       OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(),
125       OSSL_CMP_exec_CR_ses(), OSSL_CMP_exec_P10CR_ses(), and
126       OSSL_CMP_exec_KUR_ses() return a pointer to the newly obtained X509
127       certificate on success, NULL on error.  This pointer will be freed
128       implicitly by OSSL_CMP_CTX_free() or CSSL_CMP_CTX_reinit().
129
130       OSSL_CMP_try_certreq() returns 1 if the requested certificate is
131       available via OSSL_CMP_CTX_get0_newCert(3) or on successfully aborting
132       a pending certificate request, 0 on error, and -1 in case a 'waiting'
133       status has been received and checkAfter value is available.  In the
134       latter case OSSL_CMP_CTX_get0_newCert(3) yields NULL and the output
135       parameter checkAfter has been used to assign the received value unless
136       checkAfter is NULL.
137
138       OSSL_CMP_exec_RR_ses() returns 1 on success, 0 on error.
139
140       OSSL_CMP_exec_GENM_ses() returns NULL on error, otherwise a pointer to
141       the sequence of ITAV received, which may be empty.  This pointer must
142       be freed by the caller.
143

EXAMPLES

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

SEE ALSO

149       OSSL_CMP_CTX_new(3), OSSL_CMP_CTX_free(3),
150       OSSL_CMP_CTX_set1_subjectName(3), OSSL_CMP_CTX_set0_newPkey(3),
151       OSSL_CMP_CTX_set1_p10CSR(3), OSSL_CMP_CTX_set1_oldCert(3),
152       OSSL_CMP_CTX_get0_newCert(3), OSSL_CMP_CTX_push0_genm_ITAV(3),
153       OSSL_CMP_MSG_http_perform(3)
154

HISTORY

156       The OpenSSL CMP support was added in OpenSSL 3.0.
157
159       Copyright 2007-2022 The OpenSSL Project Authors. All Rights Reserved.
160
161       Licensed under the Apache License 2.0 (the "License").  You may not use
162       this file except in compliance with the License.  You can obtain a copy
163       in the file LICENSE in the source distribution or at
164       <https://www.openssl.org/source/license.html>.
165
166
167
1683.1.1                             2023-08-31      OSSL_CMP_EXEC_CERTREQ(3ossl)
Impressum