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