]>
Commit | Line | Data |
---|---|---|
fcc25beb DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
299e0f1e DDO |
5 | ossl_cmp_certreq_new, |
6 | ossl_cmp_certrep_new, | |
fcc25beb DDO |
7 | ossl_cmp_rr_new, |
8 | ossl_cmp_rp_new, | |
9 | ossl_cmp_certConf_new, | |
10 | ossl_cmp_pkiconf_new, | |
11 | ossl_cmp_pollReq_new, | |
12 | ossl_cmp_pollRep_new, | |
13 | ossl_cmp_genm_new, | |
14 | ossl_cmp_genp_new, | |
15 | ossl_cmp_error_new | |
16 | - functions for generating CMP messages | |
17 | ||
18 | =head1 SYNOPSIS | |
19 | ||
7b3990e3 | 20 | #include "cmp_local.h" |
fcc25beb | 21 | |
299e0f1e DDO |
22 | OSSL_ossl_cmp_MSG *ossl_cmp_certreq_new(OSSL_CMP_CTX *ctx, int bodytype, |
23 | const OSSL_CRMF_MSG *crm); | |
24 | OSSL_CMP_MSG *ossl_cmp_certrep_new(OSSL_CMP_CTX *ctx, int bodytype, | |
7b3990e3 DDO |
25 | int certReqId, const OSSL_CMP_PKISI *si, |
26 | X509 *cert, const X509 *encryption_recip, | |
27 | STACK_OF(X509) *chain, STACK_OF(X509) *caPubs, | |
28 | int unprotectedErrors); | |
fcc25beb | 29 | OSSL_CMP_MSG *ossl_cmp_rr_new(OSSL_CMP_CTX *ctx); |
7b3990e3 DDO |
30 | OSSL_CMP_MSG *ossl_cmp_rp_new(OSSL_CMP_CTX *ctx, const OSSL_CMP_PKISI *si, |
31 | const OSSL_CRMF_CERTID *cid, | |
32 | int unprotectedErrors); | |
fcc25beb DDO |
33 | OSSL_CMP_MSG *ossl_cmp_certConf_new(OSSL_CMP_CTX *ctx, int fail_info, |
34 | const char *text); | |
35 | OSSL_CMP_MSG *ossl_cmp_pkiconf_new(OSSL_CMP_CTX *ctx); | |
36 | OSSL_CMP_MSG *ossl_cmp_pollReq_new(OSSL_CMP_CTX *ctx, int crid); | |
f64f17c3 | 37 | OSSL_CMP_MSG *ossl_cmp_pollRep_new(OSSL_CMP_CTX *ctx, int crid, int poll_after); |
fcc25beb DDO |
38 | OSSL_CMP_MSG *ossl_cmp_genm_new(OSSL_CMP_CTX *ctx); |
39 | OSSL_CMP_MSG *ossl_cmp_genp_new(OSSL_CMP_CTX *ctx); | |
7b3990e3 | 40 | OSSL_CMP_MSG *ossl_cmp_error_new(OSSL_CMP_CTX *ctx, const OSSL_CMP_PKISI *si, |
991519ae | 41 | int64_t errorCode, const char *details, |
f64f17c3 | 42 | int unprotected); |
fcc25beb DDO |
43 | |
44 | =head1 DESCRIPTION | |
45 | ||
7b3990e3 DDO |
46 | This is the internal API for creating various CMP PKIMESSAGES. |
47 | All functions are based on L<ossl_cmp_msg_create(3)>. | |
48 | The allocate a new message, fill it with the relevant data derived from | |
49 | the given B<OSSL_CMP_CTX>, and create the applicable protection. | |
fcc25beb | 50 | |
299e0f1e | 51 | ossl_cmp_certreq_new() creates a PKIMessage for requesting a certificate, |
7b3990e3 DDO |
52 | which can be either of IR/CR/KUR/P10CR, depending on the given I<bodytype>. |
53 | The CRMF message to use may be given explicitly via a non-NULL I<crm> argument, | |
54 | otherwise it is created from the information in the I<ctx>. | |
fcc25beb | 55 | |
7b3990e3 | 56 | Available CMP certificate request PKIMessage I<bodytype>s are: |
fcc25beb DDO |
57 | |
58 | =over 4 | |
59 | ||
60 | =item * B<OSSL_CMP_PKIBODY_IR> - Initialization Request | |
61 | ||
62 | =item * B<OSSL_CMP_PKIBODY_CR> - Certification Request | |
63 | ||
64 | =item * B<OSSL_CMP_PKIBODY_P10CR> - PKCS#10 Certification Request | |
65 | ||
66 | =item * B<OSSL_CMP_PKIBODY_KUR> - Key Update Request | |
67 | ||
68 | =back | |
69 | ||
7b3990e3 DDO |
70 | ossl_cmp_certrep_new() creates a PKIMessage for certificate response, |
71 | which can be either of IP/CP/KUP, depending on the given I<bodytype>, | |
72 | with the given I<certReqId> and I<si> values and optionally with I<cert>, | |
73 | I<chain>, and I<caPubs>. The I<cert>, I<chain>, and I<caPubs> arguments | |
74 | are not consumed if present but their internal reference counter is increased. | |
75 | The I<encryption_recip> is currently unsupported. | |
76 | The function does not protect the message if the B<status> value in I<si> | |
77 | is B<rejected> and I<unprotectedErrors> is nonzero. | |
fcc25beb | 78 | |
7b3990e3 | 79 | Available CMP certificate response PKIMessage I<bodytype>s are: |
fcc25beb DDO |
80 | |
81 | =over 4 | |
82 | ||
83 | =item * B<OSSL_CMP_PKIBODY_IP> - Initialization Response | |
84 | ||
85 | =item * B<OSSL_CMP_PKIBODY_CP> - Certification Response | |
86 | ||
87 | =item * B<OSSL_CMP_PKIBODY_KUP> - Key Update Response | |
88 | ||
89 | =back | |
90 | ||
7b3990e3 | 91 | The list of all CMP PKIMessage I<bodytype>s is: |
fcc25beb DDO |
92 | |
93 | #define OSSL_CMP_PKIBODY_IR 0 | |
94 | #define OSSL_CMP_PKIBODY_IP 1 | |
95 | #define OSSL_CMP_PKIBODY_CR 2 | |
96 | #define OSSL_CMP_PKIBODY_CP 3 | |
97 | #define OSSL_CMP_PKIBODY_P10CR 4 | |
98 | #define OSSL_CMP_PKIBODY_POPDECC 5 | |
99 | #define OSSL_CMP_PKIBODY_POPDECR 6 | |
100 | #define OSSL_CMP_PKIBODY_KRR 9 | |
101 | #define OSSL_CMP_PKIBODY_KRP 10 | |
102 | #define OSSL_CMP_PKIBODY_RR 11 | |
103 | #define OSSL_CMP_PKIBODY_RP 12 | |
104 | #define OSSL_CMP_PKIBODY_CCR 13 | |
105 | #define OSSL_CMP_PKIBODY_CCP 14 | |
106 | #define OSSL_CMP_PKIBODY_CKUANN 15 | |
107 | #define OSSL_CMP_PKIBODY_CANN 16 | |
108 | #define OSSL_CMP_PKIBODY_RANN 17 | |
109 | #define OSSL_CMP_PKIBODY_CRLANN 18 | |
110 | #define OSSL_CMP_PKIBODY_PKICONF 19 | |
111 | #define OSSL_CMP_PKIBODY_NESTED 20 | |
112 | #define OSSL_CMP_PKIBODY_GENM 21 | |
113 | #define OSSL_CMP_PKIBODY_GENP 22 | |
114 | #define OSSL_CMP_PKIBODY_ERROR 23 | |
115 | #define OSSL_CMP_PKIBODY_CERTCONF 24 | |
116 | #define OSSL_CMP_PKIBODY_POLLREQ 25 | |
117 | #define OSSL_CMP_PKIBODY_POLLREP 26 | |
118 | ||
119 | ossl_cmp_rr_new() creates a Revocation Request message from the | |
120 | information set via OSSL_CMP_CTX_set1_oldClCert(). | |
121 | ||
7b3990e3 DDO |
122 | ossl_cmp_rp_new() creates a Revocation Response message with I<si> and I<cid>. |
123 | It does not protect the message if the B<status> value in I<si> is B<rejected> | |
124 | and I<unprotectedErrors> is nonzero. | |
fcc25beb DDO |
125 | |
126 | ossl_cmp_certConf_new() creates a Certificate Confirmation message for the last | |
7b3990e3 | 127 | received certificate. PKIStatus defaults to B<accepted> if the I<fail_info> bit |
fcc25beb | 128 | field is 0. Else it is taken as the failInfo of the PKIStatusInfo, PKIStatus is |
7b3990e3 | 129 | set to B<rejected>, and I<text> is copied to statusString unless it is NULL. |
fcc25beb DDO |
130 | |
131 | ossl_cmp_pkiconf_new() creates a PKI Confirmation message. | |
132 | ||
133 | ossl_cmp_pollReq_new() creates a Polling Request message with certReqId set to | |
7b3990e3 | 134 | I<crid>. |
fcc25beb DDO |
135 | |
136 | ossl_cmp_pollRep_new() creates a Polling Response message with certReqId set to | |
7b3990e3 | 137 | I<crid> and pollAfter to I<poll_after>. |
fcc25beb DDO |
138 | |
139 | ossl_cmp_genm_new() creates a new General Message with an empty ITAV stack. | |
140 | ||
141 | ossl_cmp_genp_new() creates a new General Response with an empty ITAV stack. | |
142 | ||
7b3990e3 | 143 | ossl_cmp_error_new() creates a new Error Message with the given contents |
991519ae DDO |
144 | I<si>, I<errorCode>, and optional I<details>. |
145 | If I<errorCode> is positive and in the range of an OpenSSL error code, | |
146 | the library and reason strings are included in the B<errorDetails> field. | |
147 | If given, the I<details> are added to the contents of the B<errorDetails> field. | |
148 | The function does not protect the message if I<unprotectedErrors> is nonzero. | |
fcc25beb DDO |
149 | |
150 | =head1 NOTES | |
151 | ||
152 | CMP is specified in RFC 4210 (and CRMF in RFC 4211). | |
153 | ||
154 | =head1 RETURN VALUES | |
155 | ||
156 | All of the functions return a new OSSL_CMP_MSG structure containing | |
157 | the generated message on success, or NULL on error. | |
158 | ||
159 | =head1 SEE ALSO | |
160 | ||
7b3990e3 | 161 | L<ossl_cmp_msg_create(3)>, |
fcc25beb DDO |
162 | L<OSSL_CMP_CTX_new(3)>, L<ERR_load_strings(3)> |
163 | ||
164 | =head1 HISTORY | |
165 | ||
166 | The OpenSSL CMP support was added in OpenSSL 3.0. | |
167 | ||
168 | =head1 COPYRIGHT | |
169 | ||
54b40531 | 170 | Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved. |
fcc25beb DDO |
171 | |
172 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
173 | this file except in compliance with the License. You can obtain a copy | |
174 | in the file LICENSE in the source distribution or at | |
175 | L<https://www.openssl.org/source/license.html>. | |
176 | ||
177 | =cut |