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