[openssl] master update
Richard Levitte
levitte at openssl.org
Thu Jan 14 10:38:59 UTC 2021
The branch master has been updated
via f5f4fbaa44af055e0658c6810b91aa8607e8383a (commit)
from 4369a882a565c42673b28c586a5c46a8bca98d17 (commit)
- Log -----------------------------------------------------------------
commit f5f4fbaa44af055e0658c6810b91aa8607e8383a
Author: Richard Levitte <levitte at openssl.org>
Date: Tue Jan 12 15:41:10 2021 +0100
Make the OSSL_CMP manual conform with man-pages(7)
Details from man-pages(7) that are used:
Formatting conventions for manual pages describing functions
...
Variable names should, like argument names, be specified in italics.
...
Formatting conventions (general)
...
Special macros, which are usually in uppercase, are in bold.
Exception: don't boldface NULL.
...
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13846)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/OSSL_CMP_CTX_new.pod | 2 +-
doc/man3/OSSL_CMP_ITAV_set0.pod | 18 +++++++++---------
doc/man3/OSSL_CMP_MSG_get0_header.pod | 4 ++--
doc/man3/OSSL_CMP_MSG_http_perform.pod | 4 ++--
doc/man3/OSSL_CMP_SRV_CTX_new.pod | 8 ++++----
doc/man3/OSSL_CMP_STATUSINFO_new.pod | 8 ++++----
doc/man3/OSSL_CMP_exec_certreq.pod | 32 ++++++++++++++++----------------
doc/man3/OSSL_CMP_log_open.pod | 15 ++++++++-------
doc/man3/OSSL_CMP_validate_msg.pod | 10 +++++-----
9 files changed, 51 insertions(+), 50 deletions(-)
diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod
index b468c93272..c2dfce7389 100644
--- a/doc/man3/OSSL_CMP_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_CTX_new.pod
@@ -313,7 +313,7 @@ OSSL_CMP_OPT_LOG_VERBOSITY context option to the given level.
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,
diff --git a/doc/man3/OSSL_CMP_ITAV_set0.pod b/doc/man3/OSSL_CMP_ITAV_set0.pod
index 276daa7d51..cca4537fd8 100644
--- a/doc/man3/OSSL_CMP_ITAV_set0.pod
+++ b/doc/man3/OSSL_CMP_ITAV_set0.pod
@@ -29,21 +29,21 @@ ITAV is short for InfoTypeAndValue. This type is defined in RFC 4210
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
@@ -65,7 +65,7 @@ OSSL_CMP_ITAV_push0_stack_item() returns 1 on success, 0 on error.
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);
diff --git a/doc/man3/OSSL_CMP_MSG_get0_header.pod b/doc/man3/OSSL_CMP_MSG_get0_header.pod
index 8503b74b7c..3896eb0dfb 100644
--- a/doc/man3/OSSL_CMP_MSG_get0_header.pod
+++ b/doc/man3/OSSL_CMP_MSG_get0_header.pod
@@ -39,9 +39,9 @@ then it copies the subject DN from there
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.
diff --git a/doc/man3/OSSL_CMP_MSG_http_perform.pod b/doc/man3/OSSL_CMP_MSG_http_perform.pod
index 344c6b7763..97621088f7 100644
--- a/doc/man3/OSSL_CMP_MSG_http_perform.pod
+++ b/doc/man3/OSSL_CMP_MSG_http_perform.pod
@@ -14,8 +14,8 @@ OSSL_CMP_MSG_http_perform
=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 "/".
diff --git a/doc/man3/OSSL_CMP_SRV_CTX_new.pod b/doc/man3/OSSL_CMP_SRV_CTX_new.pod
index a69df1b47d..96dd78e3ff 100644
--- a/doc/man3/OSSL_CMP_SRV_CTX_new.pod
+++ b/doc/man3/OSSL_CMP_SRV_CTX_new.pod
@@ -91,8 +91,8 @@ the respective callback function (if present) for more specific processing,
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
@@ -112,7 +112,7 @@ type of CMP message is not supported by the server.
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.
@@ -144,7 +144,7 @@ OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
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.
diff --git a/doc/man3/OSSL_CMP_STATUSINFO_new.pod b/doc/man3/OSSL_CMP_STATUSINFO_new.pod
index 2409b8cef1..fe484f6c76 100644
--- a/doc/man3/OSSL_CMP_STATUSINFO_new.pod
+++ b/doc/man3/OSSL_CMP_STATUSINFO_new.pod
@@ -25,16 +25,16 @@ OpenSSL.
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
diff --git a/doc/man3/OSSL_CMP_exec_certreq.pod b/doc/man3/OSSL_CMP_exec_certreq.pod
index 55fa73f563..895a8a9497 100644
--- a/doc/man3/OSSL_CMP_exec_certreq.pod
+++ b/doc/man3/OSSL_CMP_exec_certreq.pod
@@ -46,7 +46,7 @@ credentials the client can use for authenticating itself to the client.
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.
@@ -64,10 +64,10 @@ These four types of certificate enrollment are implemented as macros
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.
@@ -77,11 +77,11 @@ CA (or an intermedate PKI component) can fully process and answer the request.
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
@@ -95,11 +95,11 @@ OSSL_CMP_try_certreq() again with the same parameter values as before.
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
@@ -109,7 +109,7 @@ make no sense for revocation and thus are treated as an error as well.
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.
@@ -125,7 +125,7 @@ So far the CMP client implementation is limited to one request per CMP message
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().
@@ -134,15 +134,15 @@ via L<OSSL_CMP_CTX_get0_newCert(3)>
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
diff --git a/doc/man3/OSSL_CMP_log_open.pod b/doc/man3/OSSL_CMP_log_open.pod
index 5c6b924bda..1467a78147 100644
--- a/doc/man3/OSSL_CMP_log_open.pod
+++ b/doc/man3/OSSL_CMP_log_open.pod
@@ -72,10 +72,10 @@ a message string describing the nature of the event, terminated by '\n'.
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.
@@ -92,14 +92,15 @@ any pending CMP-specific log output and deallocate related resources.
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
diff --git a/doc/man3/OSSL_CMP_validate_msg.pod b/doc/man3/OSSL_CMP_validate_msg.pod
index ed2ff6c2c6..5ada09a6fe 100644
--- a/doc/man3/OSSL_CMP_validate_msg.pod
+++ b/doc/man3/OSSL_CMP_validate_msg.pod
@@ -19,17 +19,17 @@ This is the API for validating the protection of CMP messages,
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
@@ -37,7 +37,7 @@ using any trust store set via L<OSSL_CMP_CTX_set0_trustedStore(3)>.
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
@@ -48,7 +48,7 @@ validating the signatures of subsequent messages in the same transaction.
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
More information about the openssl-commits
mailing list