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