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