]>
Commit | Line | Data |
---|---|---|
3dbc5156 DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
62dcd2aa | 5 | OSSL_CMP_MSG_get0_header, |
7df56ada | 6 | OSSL_CMP_MSG_get_bodytype, |
bcd3707d | 7 | OSSL_CMP_MSG_get0_certreq_publickey, |
143be474 | 8 | OSSL_CMP_MSG_update_transactionID, |
4b0c27d4 | 9 | OSSL_CMP_MSG_update_recipNonce, |
593d6554 | 10 | OSSL_CMP_CTX_setup_CRM, |
fafa56a1 | 11 | OSSL_CMP_MSG_read, |
1202de44 | 12 | OSSL_CMP_MSG_write, |
ae8483d2 DDO |
13 | d2i_OSSL_CMP_MSG_bio, |
14 | i2d_OSSL_CMP_MSG_bio | |
3dbc5156 DDO |
15 | - function(s) manipulating CMP messages |
16 | ||
17 | =head1 SYNOPSIS | |
18 | ||
19 | #include <openssl/cmp.h> | |
20 | ||
21 | OSSL_CMP_PKIHEADER *OSSL_CMP_MSG_get0_header(const OSSL_CMP_MSG *msg); | |
7df56ada | 22 | int OSSL_CMP_MSG_get_bodytype(const OSSL_CMP_MSG *msg); |
bcd3707d | 23 | X509_PUBKEY *OSSL_CMP_MSG_get0_certreq_publickey(const OSSL_CMP_MSG *msg); |
143be474 | 24 | int OSSL_CMP_MSG_update_transactionID(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); |
4b0c27d4 | 25 | int OSSL_CMP_MSG_update_recipNonce(OSSL_CMP_CTX *ctx, OSSL_CMP_MSG *msg); |
593d6554 | 26 | OSSL_CRMF_MSG *OSSL_CMP_CTX_setup_CRM(OSSL_CMP_CTX *ctx, int for_KUR, int rid); |
5ecf10a0 | 27 | OSSL_CMP_MSG *OSSL_CMP_MSG_read(const char *file, OSSL_LIB_CTX *libctx, const char *propq); |
1202de44 | 28 | int OSSL_CMP_MSG_write(const char *file, const OSSL_CMP_MSG *msg); |
ae8483d2 DDO |
29 | OSSL_CMP_MSG *d2i_OSSL_CMP_MSG_bio(BIO *bio, OSSL_CMP_MSG **msg); |
30 | int i2d_OSSL_CMP_MSG_bio(BIO *bio, const OSSL_CMP_MSG *msg); | |
3dbc5156 DDO |
31 | |
32 | =head1 DESCRIPTION | |
33 | ||
143be474 | 34 | OSSL_CMP_MSG_get0_header() returns the header of the given CMP message. |
3dbc5156 | 35 | |
7df56ada DDO |
36 | OSSL_CMP_MSG_get_bodytype() returns the body type of the given CMP message. |
37 | ||
bcd3707d DDO |
38 | OSSL_CMP_MSG_get0_certreq_publickey() expects that I<msg> is a certificate request |
39 | messsage and returns the public key in its certificate template if present. | |
40 | ||
143be474 DDO |
41 | OSSL_CMP_MSG_update_transactionID() updates the transactionID field |
42 | in the header of the given message according to the CMP_CTX. | |
4b0c27d4 DDO |
43 | If I<ctx> does not contain a transaction ID, a fresh one is created before. |
44 | The message gets re-protected (if protecting requests is required). | |
45 | ||
46 | OSSL_CMP_MSG_update_recipNonce() updates the recipNonce field | |
47 | in the header of the given message according to the CMP_CTX. | |
48 | The message gets re-protected (if protecting requests is required). | |
143be474 | 49 | |
593d6554 | 50 | OSSL_CMP_CTX_setup_CRM() creates a CRMF certificate request message |
c8c92345 | 51 | from various information provided in the CMP context argument I<ctx> |
593d6554 | 52 | for inclusion in a CMP request message based on details contained in I<ctx>. |
c8c92345 DDO |
53 | The I<rid> argument defines the request identifier to use, which typically is 0. |
54 | ||
52a42f54 DDO |
55 | The subject DN included in the certificate template is |
56 | the first available value of these: | |
57 | ||
58 | =over 4 | |
59 | ||
7af110f9 DDO |
60 | =item any subject name in I<ctx> set via L<OSSL_CMP_CTX_set1_subjectName(3)> - |
61 | if it is the NULL-DN (i.e., any empty sequence of RDNs), no subject is included, | |
52a42f54 | 62 | |
7af110f9 DDO |
63 | =item the subject field of any PKCS#10 CSR set in I<ctx> |
64 | via L<OSSL_CMP_CTX_set1_p10CSR(3)>, | |
52a42f54 DDO |
65 | |
66 | =item the subject field of any reference certificate given in I<ctx> | |
7af110f9 | 67 | (see L<OSSL_CMP_CTX_set1_oldCert(3)>), but only if I<for_KUR> is nonzero |
52a42f54 DDO |
68 | or the I<ctx> does not include a Subject Alternative Name. |
69 | ||
70 | =back | |
71 | ||
72 | The public key included is the first available value of these: | |
73 | ||
74 | =over 4 | |
75 | ||
76 | =item the public key derived from any key set via L<OSSL_CMP_CTX_set0_newPkey(3)>, | |
77 | ||
7af110f9 | 78 | =item the public key of any PKCS#10 CSR given in I<ctx>, |
52a42f54 | 79 | |
2d658598 DDO |
80 | =item the public key of any reference certificate given in I<ctx> |
81 | (see L<OSSL_CMP_CTX_set1_oldCert(3)>), | |
52a42f54 | 82 | |
92cae9b4 DDO |
83 | =item the public key derived from any client's private key |
84 | set via L<OSSL_CMP_CTX_set1_pkey(3)>. | |
52a42f54 DDO |
85 | |
86 | =back | |
c8c92345 DDO |
87 | |
88 | The set of X.509 extensions to include is computed as follows. | |
89 | If a PKCS#10 CSR is present in I<ctx>, default extensions are taken from there, | |
90 | otherwise the empty set is taken as the initial value. | |
91 | If there is a reference certificate in I<ctx> and contains Subject Alternative | |
92 | Names (SANs) and B<OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT> is not set, | |
93 | these override any SANs from the PKCS#10 CSR. | |
94 | The extensions are further augmented or overridden by any extensions with the | |
95 | same OIDs included in the I<ctx> via L<OSSL_CMP_CTX_set0_reqExtensions(3)>. | |
96 | The SANs are further overridden by any SANs included in I<ctx> via | |
97 | L<OSSL_CMP_CTX_push1_subjectAltName(3)>. | |
98 | Finally, policies are overridden by any policies included in I<ctx> via | |
99 | L<OSSL_CMP_CTX_push0_policy(3)>. | |
100 | ||
101 | OSSL_CMP_CTX_setup_CRM() also sets the sets the regToken control B<oldCertID> | |
102 | for KUR messages using the issuer name and serial number of the reference | |
103 | certificate, if present. | |
593d6554 | 104 | |
f5f4fbaa | 105 | OSSL_CMP_MSG_read() loads a DER-encoded OSSL_CMP_MSG from I<file>. |
fafa56a1 | 106 | |
f5f4fbaa | 107 | OSSL_CMP_MSG_write() stores the given OSSL_CMP_MSG to I<file> in DER encoding. |
1202de44 | 108 | |
143be474 | 109 | d2i_OSSL_CMP_MSG_bio() parses an ASN.1-encoded OSSL_CMP_MSG from the BIO I<bio>. |
62dcd2aa DDO |
110 | It assigns a pointer to the new structure to I<*msg> if I<msg> is not NULL. |
111 | ||
143be474 | 112 | i2d_OSSL_CMP_MSG_bio() writes the OSSL_CMP_MSG I<msg> in ASN.1 encoding |
ae8483d2 | 113 | to BIO I<bio>. |
62dcd2aa | 114 | |
3dbc5156 DDO |
115 | =head1 NOTES |
116 | ||
117 | CMP is defined in RFC 4210. | |
118 | ||
119 | =head1 RETURN VALUES | |
120 | ||
62dcd2aa | 121 | OSSL_CMP_MSG_get0_header() returns the intended pointer value as described above |
3dbc5156 DDO |
122 | or NULL if the respective entry does not exist and on error. |
123 | ||
7df56ada DDO |
124 | OSSL_CMP_MSG_get_bodytype() returns the body type or -1 on error. |
125 | ||
bcd3707d DDO |
126 | OSSL_CMP_MSG_get0_certreq_publickey() returns a public key or NULL on error. |
127 | ||
7af110f9 | 128 | OSSL_CMP_CTX_setup_CRM() returns a pointer to a B<OSSL_CRMF_MSG> on success, |
593d6554 DDO |
129 | NULL on error. |
130 | ||
ae8483d2 | 131 | d2i_OSSL_CMP_MSG_bio() returns the parsed message or NULL on error. |
62dcd2aa | 132 | |
fafa56a1 DDO |
133 | OSSL_CMP_MSG_read() and d2i_OSSL_CMP_MSG_bio() |
134 | return the parsed CMP message or NULL on error. | |
135 | ||
943051d0 | 136 | OSSL_CMP_MSG_write() returns the number of bytes successfully encoded or a |
137 | negative value if an error occurs. | |
1202de44 | 138 | |
4b0c27d4 DDO |
139 | i2d_OSSL_CMP_MSG_bio(), OSSL_CMP_MSG_update_transactionID(), |
140 | and OSSL_CMP_MSG_update_recipNonce() | |
141 | return 1 on success, 0 on error. | |
62dcd2aa | 142 | |
7af110f9 DDO |
143 | =head1 SEE ALSO |
144 | ||
145 | L<OSSL_CMP_CTX_set1_subjectName(3)>, L<OSSL_CMP_CTX_set1_p10CSR(3)>, | |
146 | L<OSSL_CMP_CTX_set1_oldCert(3)>, L<OSSL_CMP_CTX_set0_newPkey(3)>, | |
147 | L<OSSL_CMP_CTX_set1_pkey(3)>, L<OSSL_CMP_CTX_set0_reqExtensions(3)>, | |
148 | L<OSSL_CMP_CTX_push1_subjectAltName(3)>, L<OSSL_CMP_CTX_push0_policy(3)> | |
149 | ||
3dbc5156 DDO |
150 | =head1 HISTORY |
151 | ||
152 | The OpenSSL CMP support was added in OpenSSL 3.0. | |
153 | ||
4b0c27d4 DDO |
154 | OSSL_CMP_MSG_update_recipNonce() was added in OpenSSL 3.0.9. |
155 | ||
bcd3707d DDO |
156 | OSSL_CMP_MSG_get0_certreq_publickey() was added in OpenSSL 3.3. |
157 | ||
3dbc5156 DDO |
158 | =head1 COPYRIGHT |
159 | ||
b6461792 | 160 | Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved. |
3dbc5156 DDO |
161 | |
162 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
163 | this file except in compliance with the License. You can obtain a copy | |
164 | in the file LICENSE in the source distribution or at | |
165 | L<https://www.openssl.org/source/license.html>. | |
166 | ||
167 | =cut |