OSSL_CMP_CTX_print_errors() outputs any entries in the OpenSSL error queue. It
is similar to L<ERR_print_errors_cb(3)> but uses the CMP log callback function
-if set in the C<ctx> for uniformity with CMP logging if given. Otherwise it uses
+if set in the I<ctx> for uniformity with CMP logging if given. Otherwise it uses
L<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host,
section 5.3.19 and Appendix F. It is used at various places in CMP messages,
e.g., in the generalInfo PKIHeader field, to hold a key-value pair.
-OSSL_CMP_ITAV_create() creates a new OSSL_CMP_ITAV structure and fills it in.
-It combines B<OSSL_CMP_ITAV_new()> and B<OSSL_CMP_ITAV_set0>.
+OSSL_CMP_ITAV_create() creates a new B<OSSL_CMP_ITAV> structure and fills it in.
+It combines OSSL_CMP_ITAV_new() and OSSL_CMP_ITAV_set0().
-OSSL_CMP_ITAV_set0() sets the B<itav> with an infoType of B<type> and an
-infoValue of B<value>. This function uses the pointers B<type> and B<value>
+OSSL_CMP_ITAV_set0() sets the I<itav> with an infoType of I<type> and an
+infoValue of I<value>. This function uses the pointers I<type> and I<value>
internally, so they must B<not> be freed up after the call.
OSSL_CMP_ITAV_get0_type() returns a direct pointer to the infoType in the
-B<itav>.
+I<itav>.
OSSL_CMP_ITAV_get0_value() returns a direct pointer to the infoValue in
-the B<itav> as generic ASN1_TYPE*.
+the I<itav> as generic B<ASN1_TYPE> pointer.
-OSSL_CMP_ITAV_push0_stack_item() pushes B<itav> to the stack pointed to
-by B<*itav_sk_p>. It creates a new stack if B<*itav_sk_p> points to NULL.
+OSSL_CMP_ITAV_push0_stack_item() pushes I<itav> to the stack pointed to
+by I<*itav_sk_p>. It creates a new stack if I<*itav_sk_p> points to NULL.
=head1 NOTES
The following code creates and sets a structure representing a generic
InfoTypeAndValue sequence, using an OID created from text as type, and an
-integer as value. Afterwards, it is pushed to the OSSL_CMP_CTX to be later
+integer as value. Afterwards, it is pushed to the B<OSSL_CMP_CTX> to be later
included in the requests' PKIHeader's genInfo field.
ASN1_OBJECT *type = OBJ_txt2obj("1.2.3.4.5", 1);
if I<for_KUR> is set or the I<ctx> does not include a subjectAltName.
The I<rid> defines the request identifier to use, which typically is 0.
-OSSL_CMP_MSG_read() loads a DER-encoded OSSL_CMP_MSG from B<file>.
+OSSL_CMP_MSG_read() loads a DER-encoded OSSL_CMP_MSG from I<file>.
-OSSL_CMP_MSG_write() stores the given OSSL_CMP_MSG to B<file> in DER encoding.
+OSSL_CMP_MSG_write() stores the given OSSL_CMP_MSG to I<file> in DER encoding.
d2i_OSSL_CMP_MSG_bio() parses an ASN.1-encoded OSSL_CMP_MSG from the BIO I<bio>.
It assigns a pointer to the new structure to I<*msg> if I<msg> is not NULL.
=head1 DESCRIPTION
-OSSL_CMP_MSG_http_perform() sends the given PKIMessage B<req>
-to the CMP server specified in B<ctx> via L<OSSL_CMP_CTX_set1_server(3)>
+OSSL_CMP_MSG_http_perform() sends the given PKIMessage I<req>
+to the CMP server specified in I<ctx> via L<OSSL_CMP_CTX_set1_server(3)>
and optionally L<OSSL_CMP_CTX_set_serverPort(3)>, using
any "CMP alias" optionally specified via L<OSSL_CMP_CTX_set1_serverPath(3)>.
The default port is 80 for HTTP and 443 for HTTPS; the default path is "/".
and then assembles a result message, which may be a CMP error message.
OSSL_CMP_CTX_server_perform() is an interface to
-B<OSSL_CMP_SRV_process_request()> that can be used by a CMP client
-in the same way as B<OSSL_CMP_MSG_http_perform()>.
+OSSL_CMP_SRV_process_request() that can be used by a CMP client
+in the same way as L<OSSL_CMP_MSG_http_perform(3)>.
The B<OSSL_CMP_SRV_CTX> must be set as I<transfer_cb_arg> of I<client_ctx>.
OSSL_CMP_SRV_CTX_new() creates and initializes an B<OSSL_CMP_SRV_CTX> structure
OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the I<srv_ctx>.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
-I<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init()>.
+I<srv_ctx> that has been set using OSSL_CMP_SRV_CTX_init().
OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
and other forms of negative responses unprotected.
NULL on error.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
-that has been set using B<OSSL_CMP_SRV_CTX_init()>.
+that has been set using OSSL_CMP_SRV_CTX_init().
All other functions return 1 on success, 0 on error.
OSSL_CMP_STATUSINFO_new() creates a new PKIStatusInfo structure
and fills in the given values.
-It sets the status field to B<status>,
-copies B<text> (unless it is NULL) to statusString,
-and interprets B<fail_info> as bit pattern for the failInfo field.
+It sets the status field to I<status>,
+copies I<text> (unless it is NULL) to statusString,
+and interprets I<fail_info> as bit pattern for the failInfo field.
OSSL_CMP_snprint_PKIStatusInfo() places a human-readable string
representing the given statusInfo
in the given buffer, with the given maximal length.
OSSL_CMP_CTX_snprint_PKIStatus() places a human-readable string
-representing the PKIStatusInfo components of the CMP context B<ctx>
+representing the PKIStatusInfo components of the CMP context I<ctx>
in the given buffer, with the given maximal length.
=head1 NOTES
In order to authenticate the server the client typically needs a trust store.
The functions return their respective main results directly, while there are
also accessor functions for retrieving various results and status information
-from the B<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.
+from the I<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.
The default conveying protocol is HTTP.
Timeout values may be given per request-response pair and per transaction.
calling OSSL_CMP_exec_certreq().
OSSL_CMP_exec_certreq() performs a certificate request of the type specified
-by the B<req_type> parameter, which may be IR, CR, P10CR, or KUR.
+by the I<req_type> parameter, which may be IR, CR, P10CR, or KUR.
For IR, CR, and KUR, the certificate template to be used in the request
-may be supplied via the B<crm> parameter pointing to a CRMF structure.
-Typically B<crm> is NULL, then the template ingredients are taken from B<ctx>
+may be supplied via the I<crm> parameter pointing to a CRMF structure.
+Typically I<crm> is NULL, then the template ingredients are taken from I<ctx>
and need to be filled in using L<OSSL_CMP_CTX_set1_subjectName(3)>,
L<OSSL_CMP_CTX_set0_newPkey(3)>, L<OSSL_CMP_CTX_set1_oldCert(3)>, etc.
For P10CR, L<OSSL_CMP_CTX_set1_p10CSR(3)> needs to be used instead.
OSSL_CMP_try_certreq() is an alternative to the above functions that is
more flexible regarding what to do after receiving a checkAfter value.
When called for the first time (with no certificate request in progress for
-the given B<ctx>) it starts a new transaction by sending a certificate request
-constructed as stated above using the B<req_type> and optional B<crm> parameter.
-Otherwise (when according to B<ctx> a 'waiting' status has been received before)
+the given I<ctx>) it starts a new transaction by sending a certificate request
+constructed as stated above using the I<req_type> and optional I<crm> parameter.
+Otherwise (when according to I<ctx> a 'waiting' status has been received before)
it continues polling for the pending request
-unless the B<req_type> argument is < 0, which aborts the request.
+unless the I<req_type> argument is < 0, which aborts the request.
If the requested certificate is available the function returns 1 and the
caller can use L<OSSL_CMP_CTX_get0_newCert(3)> to retrieve the new certificate.
If no error occurred but no certificate is available yet then
OSSL_CMP_try_certreq() then polls
to see whether meanwhile the requested certificate is available.
If the caller decides to abort the pending certificate request and provides
-a negative value as the B<req_type> argument then OSSL_CMP_try_certreq()
+a negative value as the I<req_type> argument then OSSL_CMP_try_certreq()
aborts the CMP transaction by sending an error message to the server.
OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
-specified in the B<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>.
+specified in the I<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>.
RFC 4210 is vague in which PKIStatus should be returned by the server.
We take "accepted" and "grantedWithMods" as clear success and handle
"revocationWarning" and "revocationNotification" just as warnings because CAs
OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of
infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
-provided in the B<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
+provided in the I<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
It returns the list of B<ITAV>s received in the GenRep.
This can be used, for instance, to poll for CRLs or CA Key Updates.
See RFC 4210 section 5.3.19 and appendix E.5 for details.
OSSL_CMP_exec_certreq(), OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(),
OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
-pointer to the newly obtained X509 certificate on success, B<NULL> on error.
+pointer to the newly obtained X509 certificate on success, NULL on error.
This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
CSSL_CMP_CTX_reinit().
or on successfully aborting a pending certificate request, 0 on error, and -1
in case a 'waiting' status has been received and checkAfter value is available.
In the latter case L<OSSL_CMP_CTX_get0_newCert(3)> yields NULL
-and the output parameter B<checkAfter> has been used to
-assign the received value unless B<checkAfter> is NULL.
+and the output parameter I<checkAfter> has been used to
+assign the received value unless I<checkAfter> is NULL.
OSSL_CMP_exec_RR_ses() returns the
-pointer to the revoked certificate on success, B<NULL> on error.
+pointer to the revoked certificate on success, NULL on error.
This pointer will be freed implicitly by OSSL_CMP_CTX_free().
OSSL_CMP_exec_GENM_ses() returns a
-pointer to the received B<ITAV> sequence on success, B<NULL> on error.
+pointer to the received B<ITAV> sequence on success, NULL on error.
This pointer must be freed by the caller.
=head1 EXAMPLES
Even when an activity is successful some warnings may be useful and some degree
of auditing may be required. Therefore, the logging facility supports a severity
-level and the callback function has a B<level> parameter indicating such a
+level and the callback function has a I<level> parameter indicating such a
level, such that error, warning, info, debug, etc. can be treated differently.
The callback is activated only when the severity level is sufficient according
-to the current level of verbosity, which by default is OSSL_CMP_LOG_INFO.
+to the current level of verbosity, which by default is B<OSSL_CMP_LOG_INFO>.
The callback function may itself do non-trivial tasks like writing to
a log file or remote stream, which in turn may fail.
It may be called multiple times. It does get called at OpenSSL stutdown.
OSSL_CMP_print_to_bio() prints the given component info, filename, line number,
-severity level, and log message or error queue message to the given B<bio>.
-B<component> usually is a function or module name.
+severity level, and log message or error queue message to the given I<bio>.
+I<component> usually is a function or module name.
If it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback.
OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error queue.
-It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function
-C<log_fn> for uniformity with CMP logging if not B<NULL>. Otherwise it prints to
-STDERR using B<OSSL_CMP_print_to_bio(3)> (unless OPENSSL_NO_STDIO is defined).
+It is similar to L<ERR_print_errors_cb(3)> but uses the CMP log callback
+function I<log_fn> for uniformity with CMP logging if not NULL. Otherwise it
+prints to STDERR using L<OSSL_CMP_print_to_bio(3)> (unless B<OPENSSL_NO_STDIO>
+is defined).
=head1 RETURN VALUES
which includes validating CMP message sender certificates and their paths
while optionally checking the revocation status of the certificates(s).
-OSSL_CMP_validate_msg() validates the protection of the given C<msg>
+OSSL_CMP_validate_msg() validates the protection of the given I<msg>
using either password-based mac (PBM) or a signature algorithm.
In case of signature algorithm, the certificate to use for the signature check
is preferably the one provided by a call to L<OSSL_CMP_CTX_set1_srvCert(3)>.
If no such sender cert has been pinned then candidate sender certificates are
-taken from the list of certificates received in the C<msg> extraCerts, then any
+taken from the list of certificates received in the I<msg> extraCerts, then any
certificates provided before via L<OSSL_CMP_CTX_set1_untrusted(3)>, and
then all trusted certificates provided via L<OSSL_CMP_CTX_set0_trustedStore(3)>,
where a candidate is acceptable only if has not expired, its subject DN matches
-the C<msg> sender DN (as far as present), and its subject key identifier
+the I<msg> sender DN (as far as present), and its subject key identifier
is present and matches the senderKID (as far as the latter present).
Each acceptable cert is tried in the given order to see if the message
signature check succeeds and the cert and its path can be verified
If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling
L<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message
-any self-issued certificate from the C<msg> extraCerts field may also be used
+any self-issued certificate from the I<msg> extraCerts field may also be used
as trust anchor for the path verification of an acceptable cert if it can be
used also to validate the issued certificate returned in the IP message. This is
according to TS 33.310 [Network Domain Security (NDS); Authentication Framework
OSSL_CMP_validate_cert_path() attempts to validate the given certificate and its
path using the given store of trusted certs (possibly including CRLs and a cert
-verification callback) and non-trusted intermediate certs from the B<ctx>.
+verification callback) and non-trusted intermediate certs from the I<ctx>.
=head1 NOTES