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