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