1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
=pod
=head1 NAME
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_certConf_cb
- functions implementing CMP client transactions
=head1 SYNOPSIS
#include <openssl/cmp.h>
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, int *checkAfter);
int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info,
const char **text);
X509 *OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
=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 client.
In order to authenticate the server the client typically needs a trust store.
For performing certificate enrollment requests the certificate template needs
to be sufficiently filled in, giving at least the subject name and key.
The functions return their respective main results directly, while there are
also accessor functions for retrieving various results and status information
from the B<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.
All these four types of certificate enrollment may be blocked by sleeping until the
CAs or an intermedate PKI component can fully process and answer the request.
OSSL_CMP_try_certreq() is an alternative to these four functions that is
more uniform regarding the type of the certificate request to use and
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 B<ctx>) it starts a new transaction by sending a certificate request
of the given type,
which may be IR, CR, P10CR, or KUR as specified by the B<req_type> parameter.
Otherwise (when according to B<ctx> a 'waiting' status has been received before)
it continues polling for the pending request
unless the B<req_type> argument is < 0, which aborts the request.
If the requested certificate is available the function returns 1 and the
caller can use B<OSSL_CMP_CTX_get0_newCert()> 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 B<req_type> argument then OSSL_CMP_try_certreq()
aborts the CMP transaction by sending an error message to the server.
OSSL_CMP_certConf_cb() is a basic certificate confirmation callback validating
that the new certificate can be verified with the trusted/untrusted certificates
in B<ctx>.
As there is no requirement in RFC 4210 that the certificate can be
validated by the client, this callback is not set by default in the context.
OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
specified in the B<ctx> using L<OSSL_CMP_CTX_set1_oldCert(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
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
infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
provided in the B<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
It returns the list of B<ITAV>s received in the GenRep.
This can be used, for instance, to poll for CRLs or CA Key Updates.
See RFC 4210 section 5.3.19 and appendix E.5 for details.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
So far the CMP client implementation is limited to one request per CMP message
(and consequently to at most one response component per CMP message).
=head1 RETURN VALUES
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, B<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 B<OSSL_CMP_CTX_get0_newCert()>
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 B<OSSL_CMP_CTX_get0_newCert()> yields NULL
and the output parameter B<checkAfter> has been used to
assign the received value unless B<checkAfter> is NULL.
OSSL_CMP_certConf_cb() returns B<fail_info> if it is not equal to B<0>,
else B<0> on successful validation,
or else a bit field with the B<OSSL_CMP_PKIFAILUREINFO_incorrectData> bit set.
OSSL_CMP_exec_RR_ses() returns the
pointer to the revoked certificate on success, B<NULL> on error.
This pointer will be freed implicitly by OSSL_CMP_CTX_free().
OSSL_CMP_exec_GENM_ses() returns a
pointer to the received B<ITAV> sequence on success, B<NULL> on error.
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_MSG_http_perform(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 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
|
