From: Dr. David von Oheimb Date: Mon, 21 Sep 2020 09:54:46 +0000 (+0200) Subject: openssl-cmp.pod.in: Align order of options with apps/cmp.c; improve structuring of... X-Git-Tag: openssl-3.0.0-alpha9~154 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d99c866774b815d57f6d5db0597a7e3ac37682ea;p=thirdparty%2Fopenssl.git openssl-cmp.pod.in: Align order of options with apps/cmp.c; improve structuring of SYNOPSIS Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/12932) --- diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 9ca8bbc97bf..8f483309ea5 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -3,7 +3,7 @@ =head1 NAME -openssl-cmp - client for the Certificate Management Protocol (CMP, RFC 4210) +openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application =head1 SYNOPSIS @@ -11,39 +11,16 @@ B B [B<-help>] [B<-config> I] [B<-section> I] +[B<-verbosity> I] -[B<-server> I<[http[s]://]address[:port][/path]>] -[B<-proxy> I<[http[s]://]address[:port][/path]>] -[B<-no_proxy> I] -[B<-path> I] -[B<-msg_timeout> I] -[B<-total_timeout> I] - -[B<-trusted> I] -[B<-untrusted> I] -[B<-srvcert> I] -[B<-recipient> I] -[B<-expect_sender> I] -[B<-ignore_keyusage>] -[B<-unprotected_errors>] -[B<-extracertsout> I] -[B<-cacertsout> I] +Generic message options: -[B<-ref> I] -[B<-secret> I] -[B<-cert> I] -[B<-own_trusted> I] -[B<-key> I] -[B<-keypass> I] -[B<-digest> I] -[B<-mac> I] -[B<-extracerts> I] -[B<-unprotected_requests>] - -[B<-cmd> I] +[B<-cmd> I] [B<-infotype> I] [B<-geninfo> I] +Certificate enrollment options: + [B<-newkey> I] [B<-newkeypass> I] [B<-subject> I] @@ -66,14 +43,53 @@ B B [B<-certout> I] [B<-chainout> I] +Certificate enrollment and revocation options: + [B<-oldcert> I] [B<-revreason> I] +Message transfer options: + +[B<-server> I<[http[s]://]address[:port][/path]>] +[B<-path> I] +[B<-proxy> I<[http[s]://]address[:port][/path]>] +[B<-no_proxy> I] +[B<-msg_timeout> I] +[B<-total_timeout> I] + +Server authentication options: + +[B<-trusted> I] +[B<-untrusted> I] +[B<-srvcert> I] +[B<-recipient> I] +[B<-expect_sender> I] +[B<-ignore_keyusage>] +[B<-unprotected_errors>] +[B<-extracertsout> I] +[B<-cacertsout> I] + +Client authentication options: + +[B<-ref> I] +[B<-secret> I] +[B<-cert> I] +[B<-own_trusted> I] +[B<-key> I] +[B<-keypass> I] +[B<-digest> I] +[B<-mac> I] +[B<-extracerts> I] +[B<-unprotected_requests>] + +Credentials format options: + [B<-certform> I] [B<-keyform> I] [B<-otherpass> I] -{- $OpenSSL::safe::opt_engine_synopsis -} -{- $OpenSSL::safe::opt_provider_synopsis -} +{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} + +TLS connection options: [B<-tls_used>] [B<-tls_cert> I] @@ -83,7 +99,8 @@ B B [B<-tls_trusted> I] [B<-tls_host> I] -[B<-verbosity> I] +Client-side debugging options: + [B<-batch>] [B<-repeat> I] [B<-reqin>] I @@ -93,6 +110,36 @@ B B [B<-rspout>] I [B<-use_mock_srv>] +Mock server options: + +[B<-port> I] +[B<-max_msgs> I] +[B<-srv_ref> I] +[B<-srv_secret> I] +[B<-srv_cert> I] +[B<-srv_key> I] +[B<-srv_keypass> I] +[B<-srv_trusted> I] +[B<-srv_untrusted> I] +[B<-rsp_cert> I] +[B<-rsp_extracerts> I] +[B<-rsp_capubs> I] +[B<-poll_count> I] +[B<-check_after> I] +[B<-grant_implicitconf>] +[B<-pkistatus> I] +[B<-failure> I] +[B<-failurebits> I] +[B<-statusstring> I] +[B<-send_error>] +[B<-send_unprotected>] +[B<-send_unprot_err>] +[B<-accept_unprotected>] +[B<-accept_unprot_err>] +[B<-accept_raverified>] + +Certificate verification options, for both CMP and TLS: + [B<-policy> I] [B<-purpose> I] [B<-verify_name> I] @@ -121,32 +168,6 @@ B B [B<-no_check_time>] [B<-allow_proxy_certs>] -[B<-port> I] -[B<-max_msgs> I] -[B<-srv_ref> I] -[B<-srv_secret> I] -[B<-srv_cert> I] -[B<-srv_key> I] -[B<-srv_keypass> I] -[B<-srv_trusted> I] -[B<-srv_untrusted> I] -[B<-rsp_cert> I] -[B<-rsp_extracerts> I] -[B<-rsp_capubs> I] -[B<-poll_count> I] -[B<-check_after> I] -[B<-grant_implicitconf>] -[B<-pkistatus> I] -[B<-failure> I] -[B<-failurebits> I] -[B<-statusstring> I] -[B<-send_error>] -[B<-send_unprotected>] -[B<-send_unprot_err>] -[B<-accept_unprotected>] -[B<-accept_unprot_err>] -[B<-accept_raverified>] - =head1 DESCRIPTION The B command is a client implementation for the Certificate @@ -181,8 +202,14 @@ Contents of sections named later may override contents of sections named before. In any case, as usual, the C<[default]> section and finally the unnamed section (as far as present) can provide per-option fallback values. -=back +=item B<-verbosity> I +Level of verbosity for logging, error output, etc. +0 = EMERG, 1 = ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE, +6 = INFO, 7 = DEBUG, 8 = TRACE. +Defaults to 6 = INFO. + +=back =head2 Generic message options @@ -239,8 +266,7 @@ e.g., C<1.2.3.4:int:56789>. =back - -=head2 Certificate request options +=head2 Certificate enrollment options =over 4 @@ -391,8 +417,7 @@ The file where the chain of the newly enrolled certificate should be saved. =back - -=head2 Certificate revocation options +=head2 Certificate enrollment and revocation options =over 4 @@ -431,7 +456,6 @@ Reason numbers defined in RFC 5280 are: =back - =head2 Message transfer options =over 4 @@ -443,6 +467,11 @@ of the CMP server to connect to using HTTP(S) transport. The optional I or I prefix is ignored. If a path is included it provides the default value for the B<-path> option. +=item B<-path> I + +HTTP path at the CMP server (aka CMP alias) to use for POST requests. +Defaults to any path given with B<-server>, else C<"/">. + =item B<-proxy> I<[http[s]://]address[:port][/path]> The HTTP(S) proxy server to use for reaching the CMP server unless B @@ -458,11 +487,6 @@ not to use an HTTP(S) proxy for, separated by commas and/or whitespace (where in the latter case the whole argument must be enclosed in "..."). Default is from the environment variable C if set, else C. -=item B<-path> I - -HTTP path at the CMP server (aka CMP alias) to use for POST requests. -Defaults to any path given with B<-server>, else C<"/">. - =item B<-msg_timeout> I Number of seconds (or 0 for infinite) a CMP request-response message round trip @@ -477,7 +501,6 @@ Default is 0 (infinite). =back - =head2 Server authentication options =over 4 @@ -601,7 +624,6 @@ the last received certificate response (i.e., IP, CP, or KUP) message. =back - =head2 Client authentication options =over 4 @@ -699,7 +721,6 @@ Send messages without CMP-level protection. =back - =head2 Credentials format options =over 4 @@ -746,8 +767,7 @@ C<-key engine:pkcs11:object=my-private-key;type=private;pin-value=1234> =back - -=head2 TLS options +=head2 TLS connection options =over 4 @@ -796,18 +816,10 @@ If not given it defaults to the B<-server> address. =back - =head2 Client-side debugging options =over 4 -=item B<-verbosity> I - -Level of verbosity for logging, error output, etc. -0 = EMERG, 1 = ALERT, 2 = CRIT, 3 = ERR, 4 = WARN, 5 = NOTE, -6 = INFO, 7 = DEBUG, 8 = TRACE. -Defaults to 6 = INFO. - =item B<-batch> Do not interactively prompt for input, for instance when a password is needed. @@ -861,31 +873,7 @@ This works at API level, bypassing HTTP transport. =back - -=head2 Certificate verification options, for both CMP and TLS - -=over 4 - -=item B<-policy>, B<-purpose>, B<-verify_name>, B<-verify_depth>, -B<-attime>, -B<-ignore_critical>, B<-issuer_checks>, -B<-policy_check>, -B<-explicit_policy>, B<-inhibit_any>, B<-inhibit_map>, -B<-x509_strict>, B<-extended_crl>, B<-use_deltas>, -B<-policy_print>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, -B<-trusted_first>, -B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>, -B<-partial_chain>, B<-no_alt_chains>, B<-no_check_time>, -B<-auth_level>, -B<-allow_proxy_certs> - -Set various options of certificate chain verification. -See L for details. - -=back - - -=head2 Mock server options, for testing purposes only +=head2 Mock server options =over 4 @@ -949,7 +937,6 @@ Number of times the client must poll before receiving a certificate. The checkAfter value (number of seconds to wait) to include in poll response. - =item B<-grant_implicitconf> Grant implicit confirmation of newly enrolled certificate. @@ -1000,6 +987,27 @@ Accept RAVERIFED as proof-of-possession (POPO). =back +=head2 Certificate verification options, for both CMP and TLS + +=over 4 + +=item B<-policy>, B<-purpose>, B<-verify_name>, B<-verify_depth>, +B<-attime>, +B<-ignore_critical>, B<-issuer_checks>, +B<-policy_check>, +B<-explicit_policy>, B<-inhibit_any>, B<-inhibit_map>, +B<-x509_strict>, B<-extended_crl>, B<-use_deltas>, +B<-policy_print>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-trusted_first>, +B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>, +B<-partial_chain>, B<-no_alt_chains>, B<-no_check_time>, +B<-auth_level>, +B<-allow_proxy_certs> + +Set various options of certificate chain verification. +See L for details. + +=back =head1 NOTES @@ -1013,7 +1021,6 @@ although they usually contain hints that would be helpful for diagnostics. For assisting in such cases the CMP client offers a workaround via the B<-unprotected_errors> option, which allows accepting such negative messages. - =head1 EXAMPLES =head2 Simple examples using the default OpenSSL configuration file @@ -1113,13 +1120,12 @@ In below command line usage examples the C<\> at line ends is just used for formatting; each of the command invocations should be on a single line. openssl genrsa -out cl_key.pem - openssl cmp -cmd ir -server 127.0.0.1:80 -path pkix/ \ + openssl cmp -cmd ir -server 127.0.0.1:80/pkix/ \ -ref 1234 -secret pass:1234-5678-1234-5678 \ -recipient "/CN=CMPserver" \ -newkey cl_key.pem -subject "/CN=MyName" \ -cacertsout capubs.pem -certout cl_cert.pem - =head2 Certificate update Then, when the client certificate and its related key pair needs to be updated, @@ -1129,7 +1135,7 @@ for its own authentication. Then it can start using the new cert and key. openssl genrsa -out cl_key_new.pem - openssl cmp -cmd kur -server 127.0.0.1:80 -path pkix/ \ + openssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \ -trusted capubs.pem \ -cert cl_cert.pem -key cl_key.pem \ -newkey cl_key_new.pem -certout cl_cert.pem @@ -1137,17 +1143,15 @@ Then it can start using the new cert and key. This command sequence can be repated as often as needed. - =head2 Requesting information from CMP server Requesting "all relevant information" with an empty General Message. This prints information about all received ITAV Bs to stdout. - openssl cmp -cmd genm -server 127.0.0.1 -path pkix/ \ + openssl cmp -cmd genm -server 127.0.0.1/pkix/ \ -ref 1234 -secret pass:1234-5678-1234-5678 \ -recipient "/CN=CMPserver" - =head2 Using a custom configuration file For CMP client invocations, in particular for certificate enrollment,