The branch master has been updated via ac093b3fe6ba3f21e874a25ddecc7c1b4dff2765 (commit) via b6f18ed2effbefc52b392980f79cbe97f10bdb00 (commit) via 6b480ee369ae81a664518f440c2f7de94afc3b00 (commit) from 9256e8a2487697c347f8e54db69509dc662b26f7 (commit)
- Log ----------------------------------------------------------------- commit ac093b3fe6ba3f21e874a25ddecc7c1b4dff2765 Author: Ankita Shetty <ankita.s.shett...@gmail.com> Date: Fri Nov 27 17:05:30 2020 +0100 openssl.pod: Carve out Trusted Certificate, Pass Phrase, Name Format, and Format Options Move detailed doc to specific new files in doc/man1/openssl-*-options.pod Reviewed-by: Tomas Mraz <tm...@fedoraproject.org> Reviewed-by: David von Oheimb <david.von.ohe...@siemens.com> (Merged from https://github.com/openssl/openssl/pull/13315) commit b6f18ed2effbefc52b392980f79cbe97f10bdb00 Author: David von Oheimb <d...@ddvo.net> Date: Wed Nov 4 14:04:27 2020 +0100 openssl.pod: Move verification doc to new doc/man1/openssl-verification-options.pod Reviewed-by: Tomas Mraz <tm...@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13315) commit 6b480ee369ae81a664518f440c2f7de94afc3b00 Author: Dr. David von Oheimb <david.von.ohe...@siemens.com> Date: Fri Nov 20 12:29:32 2020 +0100 find-doc-nits: fix regexp and point out that CA.pl and tsget.pod are special Reviewed-by: Tomas Mraz <tm...@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13315) ----------------------------------------------------------------------- Summary of changes: doc/man1/openssl-asn1parse.pod.in | 2 +- doc/man1/openssl-ca.pod.in | 4 +- doc/man1/openssl-cms.pod.in | 12 +- doc/man1/openssl-crl.pod.in | 2 +- doc/man1/openssl-crl2pkcs7.pod.in | 4 +- doc/man1/openssl-dgst.pod.in | 4 +- doc/man1/openssl-dhparam.pod.in | 2 +- doc/man1/openssl-dsa.pod.in | 4 +- doc/man1/openssl-dsaparam.pod.in | 2 +- doc/man1/openssl-ec.pod.in | 6 +- doc/man1/openssl-ecparam.pod.in | 2 +- doc/man1/openssl-enc.pod.in | 2 +- doc/man1/openssl-format-options.pod | 143 ++++++ doc/man1/openssl-gendsa.pod.in | 2 +- doc/man1/openssl-genpkey.pod.in | 4 +- doc/man1/openssl-genrsa.pod.in | 2 +- doc/man1/openssl-namefmt-options.pod | 179 ++++++++ doc/man1/openssl-ocsp.pod.in | 2 +- doc/man1/openssl-passphrase-options.pod | 75 ++++ doc/man1/openssl-pkcs12.pod.in | 5 +- doc/man1/openssl-pkcs7.pod.in | 2 +- doc/man1/openssl-pkcs8.pod.in | 4 +- doc/man1/openssl-pkey.pod.in | 6 +- doc/man1/openssl-pkeyutl.pod.in | 6 +- doc/man1/openssl-req.pod.in | 6 +- doc/man1/openssl-rsa.pod.in | 6 +- doc/man1/openssl-rsautl.pod.in | 4 +- doc/man1/openssl-s_client.pod.in | 8 +- doc/man1/openssl-s_server.pod.in | 10 +- doc/man1/openssl-sess_id.pod.in | 2 +- doc/man1/openssl-smime.pod.in | 8 +- doc/man1/openssl-spkac.pod.in | 4 +- doc/man1/openssl-srp.pod.in | 2 +- doc/man1/openssl-storeutl.pod.in | 2 +- doc/man1/openssl-ts.pod.in | 4 +- doc/man1/openssl-verification-options.pod | 453 +++++++++++++++++++ doc/man1/openssl-verify.pod.in | 2 +- doc/man1/openssl-x509.pod.in | 10 +- doc/man1/openssl.pod | 711 +----------------------------- doc/man3/X509_verify_cert.pod | 2 +- doc/perlvars.pm | 8 +- util/find-doc-nits | 3 +- 42 files changed, 937 insertions(+), 784 deletions(-) create mode 100644 doc/man1/openssl-format-options.pod create mode 100644 doc/man1/openssl-namefmt-options.pod create mode 100644 doc/man1/openssl-passphrase-options.pod create mode 100644 doc/man1/openssl-verification-options.pod diff --git a/doc/man1/openssl-asn1parse.pod.in b/doc/man1/openssl-asn1parse.pod.in index bafcc225d9..62b7e626ef 100644 --- a/doc/man1/openssl-asn1parse.pod.in +++ b/doc/man1/openssl-asn1parse.pod.in @@ -41,7 +41,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM> The input format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-in> I<filename> diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in index 64a7054d63..8442c4450b 100644 --- a/doc/man1/openssl-ca.pod.in +++ b/doc/man1/openssl-ca.pod.in @@ -156,7 +156,7 @@ The CA private key to sign requests with. This must match with B<-cert>. The format of the private key input file; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-sigopt> I<nm>:I<v> @@ -186,7 +186,7 @@ Better use B<-passin>. The key password source for key files and certificate PKCS#12 files. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-selfsign> diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index fc2bae1bce..f5872f2261 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -228,25 +228,25 @@ format message that has been signed or verified. The input format of the CMS structure (if one is being read); the default is B<SMIME>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM>|B<SMIME> The output format of the CMS structure (if one is being written); the default is B<SMIME>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> The format of the private key file; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-rctform> B<DER>|B<PEM>|B<SMIME> The signed receipt format for use with the B<-receipt_verify>; the default is B<SMIME>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-stream>, B<-indef> @@ -293,7 +293,7 @@ is mainly useful for testing purposes. For the B<-cmsout> operation when B<-print> option is in use, specifies printing options for string fields. For most cases B<utf8> is reasonable value. -See L<openssl(1)/Name Format Options> for details. +See L<openssl-namefmt-options(1)/Name Format Options> for details. =item B<-md> I<digest> @@ -484,7 +484,7 @@ or to modify default parameters for ECDH. =item B<-passin> I<arg> The private key password source. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-to>, B<-from>, B<-subject> diff --git a/doc/man1/openssl-crl.pod.in b/doc/man1/openssl-crl.pod.in index 19e72f1b60..98404c7b4a 100644 --- a/doc/man1/openssl-crl.pod.in +++ b/doc/man1/openssl-crl.pod.in @@ -53,7 +53,7 @@ This option has no effect and is retained for backward compatibility only. =item B<-outform> B<DER>|B<PEM> The CRL output format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-key> I<filename> diff --git a/doc/man1/openssl-crl2pkcs7.pod.in b/doc/man1/openssl-crl2pkcs7.pod.in index bc39d6dcae..5dcd7a933b 100644 --- a/doc/man1/openssl-crl2pkcs7.pod.in +++ b/doc/man1/openssl-crl2pkcs7.pod.in @@ -34,12 +34,12 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM> The input format of the CRL; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM> The output format of the PKCS#7 object; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-in> I<filename> diff --git a/doc/man1/openssl-dgst.pod.in b/doc/man1/openssl-dgst.pod.in index 6276fab434..6679973c0e 100644 --- a/doc/man1/openssl-dgst.pod.in +++ b/doc/man1/openssl-dgst.pod.in @@ -110,7 +110,7 @@ command instead for this. The format of the key to sign with; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-sigopt> I<nm>:I<v> @@ -120,7 +120,7 @@ Names and values of these options are algorithm-specific. =item B<-passin> I<arg> The private key password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-verify> I<filename> diff --git a/doc/man1/openssl-dhparam.pod.in b/doc/man1/openssl-dhparam.pod.in index 2b67943f1f..778747df59 100644 --- a/doc/man1/openssl-dhparam.pod.in +++ b/doc/man1/openssl-dhparam.pod.in @@ -42,7 +42,7 @@ Print out a usage message. The input format and output format; the default is B<PEM>. The object is compatible with the PKCS#3 B<DHparameter> structure. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-in> I<filename> diff --git a/doc/man1/openssl-dsa.pod.in b/doc/man1/openssl-dsa.pod.in index bce965c322..f1839341ed 100644 --- a/doc/man1/openssl-dsa.pod.in +++ b/doc/man1/openssl-dsa.pod.in @@ -58,7 +58,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> The input and formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. Private keys are a sequence of B<ASN.1 INTEGERS>: the version (zero), B<p>, B<q>, B<g>, and the public and private key components. Public keys @@ -83,7 +83,7 @@ filename. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea> diff --git a/doc/man1/openssl-dsaparam.pod.in b/doc/man1/openssl-dsaparam.pod.in index 42aea39a06..f7c3eafb0f 100644 --- a/doc/man1/openssl-dsaparam.pod.in +++ b/doc/man1/openssl-dsaparam.pod.in @@ -39,7 +39,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> This option has become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. Parameters are a sequence of B<ASN.1 INTEGER>s: B<p>, B<q>, and B<g>. This is compatible with RFC 2459 B<DSS-Parms> structure. diff --git a/doc/man1/openssl-ec.pod.in b/doc/man1/openssl-ec.pod.in index 2ba107d031..befae6990b 100644 --- a/doc/man1/openssl-ec.pod.in +++ b/doc/man1/openssl-ec.pod.in @@ -55,12 +55,12 @@ Print out a usage message. The key input format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM> The key output formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. Private keys are an SEC1 private key or PKCS#8 format. Public keys are a B<SubjectPublicKeyInfo> as specified in IETF RFC 3280. @@ -82,7 +82,7 @@ filename. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-des>|B<-des3>|B<-idea> diff --git a/doc/man1/openssl-ecparam.pod.in b/doc/man1/openssl-ecparam.pod.in index a77ddd0128..26fd0af97b 100644 --- a/doc/man1/openssl-ecparam.pod.in +++ b/doc/man1/openssl-ecparam.pod.in @@ -46,7 +46,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> The input and formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. Parameters are encoded as B<EcpkParameters> as specified in IETF RFC 3279. diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in index 675e360d5e..2665ddc2af 100644 --- a/doc/man1/openssl-enc.pod.in +++ b/doc/man1/openssl-enc.pod.in @@ -79,7 +79,7 @@ The output filename, standard output by default. =item B<-pass> I<arg> The password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-e> diff --git a/doc/man1/openssl-format-options.pod b/doc/man1/openssl-format-options.pod new file mode 100644 index 0000000000..20b62f9b15 --- /dev/null +++ b/doc/man1/openssl-format-options.pod @@ -0,0 +1,143 @@ +=pod + +=head1 NAME + +openssl-format-options - OpenSSL command input and output format options + +=head1 SYNOPSIS + +B<openssl> +I<command> +[ I<options> ... ] +[ I<parameters> ... ] + +=head1 DESCRIPTION + +Several OpenSSL commands can take input or generate output in a variety +of formats. +Since OpenSSL 3.0 keys, single certificates, and CRLs can be read from +files in any of the B<DER>, B<PEM> or B<P12> formats, +while specifying their input format is no more needed. +In order to access a key via an engine the input format B<ENGINE> may be used; +alternatively the key identifier in the <uri> argument of the respective key +option may be preceded by C<org.openssl.engine:>. +See L<openssl(1)/Engine Options> for an example usage of the latter. + +=head1 OPTIONS + +=head2 Format Options + +The options to specify the format are as follows. +Refer to the individual man page to see which options are accepted. + +=over 4 + +=item B<-inform> I<format>, B<-outform> I<format> + +The format of the input or output streams. + +=item B<-keyform> I<format> + +Format of a private key input source. +The only value with effect is B<ENGINE>; all others have become obsolete. +See L<openssl(1)/Format Options> for details. + +=item B<-CRLform> I<format> + +Format of a CRL input source. + +=back + +=head2 Format Option Arguments + +The possible format arguments are described below. +Both uppercase and lowercase are accepted. + +The list of acceptable format arguments, and the default, +is described in each command documentation. + +=over 4 + +=item B<DER> + +A binary format, encoded or parsed according to Distinguished Encoding Rules +(DER) of the ASN.1 data language. + +=item B<ENGINE> + +Used to specify that the cryptographic material is in an OpenSSL B<engine>. +An engine must be configured or specified using the B<-engine> option. +A password or PIN may be supplied to the engine using the B<-passin> option. + +=item B<P12> + +A DER-encoded file containing a PKCS#12 object. +It might be necessary to provide a decryption password to retrieve +the private key. + +=item B<PEM> + +A text format defined in IETF RFC 1421 and IETF RFC 7468. Briefly, this is +a block of base-64 encoding (defined in IETF RFC 4648), with specific +lines used to mark the start and end: + + Text before the BEGIN line is ignored. + ----- BEGIN object-type ----- + OT43gQKBgQC/2OHZoko6iRlNOAQ/tMVFNq7fL81GivoQ9F1U0Qr+DH3ZfaH8eIkX + xT0ToMPJUzWAn8pZv0snA0um6SIgvkCuxO84OkANCVbttzXImIsL7pFzfcwV/ERK + UM6j0ZuSMFOCr/lGPAoOQU0fskidGEHi1/kW+suSr28TqsyYZpwBDQ== + ----- END object-type ----- + Text after the END line is also ignored + +The I<object-type> must match the type of object that is expected. +For example a C<BEGIN X509 CERTIFICATE> will not match if the command +is trying to read a private key. The types supported include: + + ANY PRIVATE KEY + CERTIFICATE + CERTIFICATE REQUEST + CMS + DH PARAMETERS + DSA PARAMETERS + DSA PUBLIC KEY + EC PARAMETERS + EC PRIVATE KEY + ECDSA PUBLIC KEY + ENCRYPTED PRIVATE KEY + PARAMETERS + PKCS #7 SIGNED DATA + PKCS7 + PRIVATE KEY + PUBLIC KEY + RSA PRIVATE KEY + SSL SESSION PARAMETERS + TRUSTED CERTIFICATE + X509 CRL + X9.42 DH PARAMETERS + +The following legacy I<object-type>'s are also supported for compatibility +with earlier releases: + + DSA PRIVATE KEY + NEW CERTIFICATE REQUEST + RSA PUBLIC KEY + X509 CERTIFICATE + +=item B<SMIME> + +An S/MIME object as described in IETF RFC 8551. +Earlier versions were known as CMS and are compatible. +Note that the parsing is simple and might fail to parse some legal data. + +=back + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man1/openssl-gendsa.pod.in b/doc/man1/openssl-gendsa.pod.in index 3b7579c5a5..e62e0706cb 100644 --- a/doc/man1/openssl-gendsa.pod.in +++ b/doc/man1/openssl-gendsa.pod.in @@ -51,7 +51,7 @@ standard output is used. =item B<-passout> I<arg> The passphrase used for the output file. -See L<openssl(1)/Pass Phrase Options>. +See L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea> diff --git a/doc/man1/openssl-genpkey.pod.in b/doc/man1/openssl-genpkey.pod.in index 97a60c6968..14b5767c94 100644 --- a/doc/man1/openssl-genpkey.pod.in +++ b/doc/man1/openssl-genpkey.pod.in @@ -47,14 +47,14 @@ standard output is used. =item B<-outform> B<DER>|B<PEM> The output format, except when B<-genparam> is given; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. When B<-genparam> is given, B<-outform> is ignored. =item B<-pass> I<arg> The output file password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-I<cipher>> diff --git a/doc/man1/openssl-genrsa.pod.in b/doc/man1/openssl-genrsa.pod.in index cc4ad6ae0d..f524bb860b 100644 --- a/doc/man1/openssl-genrsa.pod.in +++ b/doc/man1/openssl-genrsa.pod.in @@ -58,7 +58,7 @@ standard output is used. =item B<-passout> I<arg> The output file password source. For more information about the format -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea> diff --git a/doc/man1/openssl-namefmt-options.pod b/doc/man1/openssl-namefmt-options.pod new file mode 100644 index 0000000000..d92abd406b --- /dev/null +++ b/doc/man1/openssl-namefmt-options.pod @@ -0,0 +1,179 @@ +=pod + +=head1 NAME + +openssl-namefmt-options - DN display options + +=head1 SYNOPSIS + +B<openssl> +I<command> +[ I<options> ... ] +[ I<parameters> ... ] + +=head1 DESCRIPTION + +OpenSSL provides fine-grain control over how the subject and issuer DN's are +displayed. +This is specified by using the B<-nameopt> option, which takes a +comma-separated list of options from the following set. +An option may be preceded by a minus sign, C<->, to turn it off. +The default value is C<oneline>. +The first four are the most commonly used. + +=head1 OPTIONS + +=head2 Name Format Option Arguments + +The DN output format can be fine tuned with the following flags. + +=over 4 + +=item B<compat> + +Display the name using an old format from previous OpenSSL versions. + +=item B<RFC2253> + +Display the name using the format defined in RFC 2253. +It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, +B<dump_nostr>, B<dump_unknown>, B<dump_der>, B<sep_comma_plus>, B<dn_rev> +and B<sname>. + +=item B<oneline> + +Display the name in one line, using a format that is more readable +RFC 2253. +It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, +B<dump_nostr>, B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, +B<space_eq> and B<sname> options. + +=item B<multiline> + +Display the name using multiple lines. +It is equivalent to B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, B<space_eq>, +B<lname> and B<align>. + +=item B<esc_2253> + +Escape the "special" characters in a field, as required by RFC 2253. +That is, any of the characters C<,+"E<lt>E<gt>;>, C<#> at the beginning of +a string and leading or trailing spaces. + +=item B<esc_2254> + +Escape the "special" characters in a field as required by RFC 2254 in a field. +That is, the B<NUL> character and of C<()*>. + +=item B<esc_ctrl> + +Escape non-printable ASCII characters, codes less than 0x20 (space) +or greater than 0x7F (DELETE). They are displayed using RFC 2253 C<\XX> +notation where B<XX> are the two hex digits representing the character value. + +=item B<esc_msb> + +Escape any characters with the most significant bit set, that is with +values larger than 127, as described in B<esc_ctrl>. + +=item B<use_quote> + +Escapes some characters by surrounding the entire string with quotation +marks, C<">. +Without this option, individual special characters are preceded with +a backslash character, C<\>. + +=item B<utf8> + +Convert all strings to UTF-8 format first as required by RFC 2253. +If the output device is UTF-8 compatible, then using this option (and +not setting B<esc_msb>) may give the correct display of multibyte +characters. +If this option is not set, then multibyte characters larger than 0xFF +will be output as C<\UXXXX> for 16 bits or C<\WXXXXXXXX> for 32 bits. +In addition, any UTF8Strings will be converted to their character form first. + +=item B<ignore_type> + +This option does not attempt to interpret multibyte characters in any +way. That is, the content octets are merely dumped as though one octet +represents each character. This is useful for diagnostic purposes but +will result in rather odd looking output. + +=item B<show_type> + +Display the type of the ASN1 character string before the value, +such as C<BMPSTRING: Hello World>. + +=item B<dump_der> + +Any fields that would be output in hex format are displayed using +the DER encoding of the field. +If not set, just the content octets are displayed. +Either way, the B<#XXXX...> format of RFC 2253 is used. + +=item B<dump_nostr> + +Dump non-character strings, such as ASN.1 B<OCTET STRING>. +If this option is not set, then non character string types will be displayed +as though each content octet represents a single character. + +=item B<dump_all> + +Dump all fields. When this used with B<dump_der>, this allows the +DER encoding of the structure to be unambiguously determined. + +=item B<dump_unknown> + +Dump any field whose OID is not recognised by OpenSSL. + +=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, +B<sep_multiline> + +Specify the field separators. The first word is used between the +Relative Distinguished Names (RDNs) and the second is between +multiple Attribute Value Assertions (AVAs). Multiple AVAs are +very rare and their use is discouraged. +The options ending in "space" additionally place a space after the separator to make it more readable. +The B<sep_multiline> starts each field on its own line, and uses "plus space" +for the AVA separator. +It also indents the fields by four characters. +The default value is B<sep_comma_plus_space>. + +=item B<dn_rev> + +Reverse the fields of the DN as required by RFC 2253. +This also reverses the order of multiple AVAs in a field, but this is +permissible as there is no ordering on values. + +=item B<nofname>, B<sname>, B<lname>, B<oid> + +Specify how the field name is displayed. +B<nofname> does not display the field at all. +B<sname> uses the "short name" form (CN for commonName for example). +B<lname> uses the long form. +B<oid> represents the OID in numerical form and is useful for +diagnostic purpose. + +=item B<align> + +Align field values for a more readable output. Only usable with +B<sep_multiline>. + +=item B<space_eq> + +Places spaces round the equal sign, C<=>, character which follows the field +name. + +=back + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man1/openssl-ocsp.pod.in b/doc/man1/openssl-ocsp.pod.in index 614a4dae83..a3e9d3e504 100644 --- a/doc/man1/openssl-ocsp.pod.in +++ b/doc/man1/openssl-ocsp.pod.in @@ -314,7 +314,7 @@ specified in the B<-rsigner> option is used. =item B<-passin> I<arg> The private key password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-rother> I<file> diff --git a/doc/man1/openssl-passphrase-options.pod b/doc/man1/openssl-passphrase-options.pod new file mode 100644 index 0000000000..abc43fb41e --- /dev/null +++ b/doc/man1/openssl-passphrase-options.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +openssl-passphrase-options - Pass phrase options + +=head1 SYNOPSIS + +B<openssl> +I<command> +[ I<options> ... ] +[ I<parameters> ... ] + +=head1 DESCRIPTION + +Several OpenSSL commands accept password arguments, typically using B<-passin> +and B<-passout> for input and output passwords respectively. These allow +the password to be obtained from a variety of sources. Both of these +options take a single argument whose format is described below. If no +password argument is given and a password is required then the user is +prompted to enter one: this will typically be read from the current +terminal with echoing turned off. + +Note that character encoding may be relevant, please see +L<passphrase-encoding(7)>. + +=head1 OPTIONS + +=head2 Pass Phrase Option Arguments + +Pass phrase arguments can be formatted as follows. + +=over 4 + +=item B<pass:>I<password> + +The actual password is I<password>. Since the password is visible +to utilities (like 'ps' under Unix) this form should only be used +where security is not important. + +=item B<env:>I<var> + +Obtain the password from the environment variable I<var>. Since +the environment of other processes is visible on certain platforms +(e.g. ps under certain Unix OSes) this option should be used with caution. + +=item B<file:>I<pathname> + +The first line of I<pathname> is the password. If the same I<pathname> +argument is supplied to B<-passin> and B<-passout> arguments then the first +line will be used for the input password and the next line for the output +password. I<pathname> need not refer to a regular file: it could for example +refer to a device or named pipe. + +=item B<fd:>I<number> + +Read the password from the file descriptor I<number>. This can be used to +send the data via a pipe for example. + +=item B<stdin> + +Read the password from standard input. + +=back + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in index 3b573be6d1..b9565144da 100644 --- a/doc/man1/openssl-pkcs12.pod.in +++ b/doc/man1/openssl-pkcs12.pod.in @@ -95,9 +95,10 @@ Print out a usage message. =item B<-passin> I<arg> -The password source for input files. +The password source for the input, and for encrypting any private keys that +are output. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-passout> I<arg> diff --git a/doc/man1/openssl-pkcs7.pod.in b/doc/man1/openssl-pkcs7.pod.in index fff54d312a..3a28adc1ab 100644 --- a/doc/man1/openssl-pkcs7.pod.in +++ b/doc/man1/openssl-pkcs7.pod.in @@ -42,7 +42,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> The input and formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. The data is a PKCS#7 Version 1.5 structure. diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in index 968583ee0a..6ff6e8bc75 100644 --- a/doc/man1/openssl-pkcs8.pod.in +++ b/doc/man1/openssl-pkcs8.pod.in @@ -55,7 +55,7 @@ reversed: it reads a private key and writes a PKCS#8 format key. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> The input and formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is not used) then the input file must be in PKCS#8 format. An encrypted @@ -88,7 +88,7 @@ prompted for. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-out> I<filename> diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in index b1afeb534b..14a8a63841 100644 --- a/doc/man1/openssl-pkey.pod.in +++ b/doc/man1/openssl-pkey.pod.in @@ -51,12 +51,12 @@ Print out a usage message. The key input format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM> The key output formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-in> I<filename>|I<uri> @@ -68,7 +68,7 @@ prompted for. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-out> I<filename> diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in index a35c4dae65..b657440f7e 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -93,12 +93,12 @@ The input key, by default it should be a private key. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-passin> I<arg> The input key password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-peerkey> I<file> @@ -108,7 +108,7 @@ The peer key file, used by key derivation (agreement) operations. The peer key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-pubin> diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index 8fa5191702..9b3242d28a 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -72,7 +72,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> The input and formats; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. The data is a PKCS#10 object. @@ -104,7 +104,7 @@ which supports both options for good reasons. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-out> I<filename> @@ -190,7 +190,7 @@ accepts PKCS#8 format private keys for PEM format files. The format of the private key; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-keyout> I<filename> diff --git a/doc/man1/openssl-rsa.pod.in b/doc/man1/openssl-rsa.pod.in index f2e7f3474c..1eebef83ef 100644 --- a/doc/man1/openssl-rsa.pod.in +++ b/doc/man1/openssl-rsa.pod.in @@ -62,12 +62,12 @@ Print out a usage message. The key input format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM> The key output format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-traditional> @@ -84,7 +84,7 @@ prompted for. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-out> I<filename> diff --git a/doc/man1/openssl-rsautl.pod.in b/doc/man1/openssl-rsautl.pod.in index fed453b940..fca0fdbf4c 100644 --- a/doc/man1/openssl-rsautl.pod.in +++ b/doc/man1/openssl-rsautl.pod.in @@ -60,7 +60,7 @@ if this option is not specified. =item B<-passin> I<arg> The passphrase used in the output file. -See see L<openssl(1)/Pass Phrase Options>. +See see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-rev> @@ -79,7 +79,7 @@ The input key, by default it should be an RSA private key. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-pubin> diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index ddaa69c1b7..66fd051591 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -198,7 +198,7 @@ the network. Use with caution. The proxy password source, used with the B<-proxy_user> flag. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-unix> I<path> @@ -263,7 +263,7 @@ CRL file to use to check the server's certificate. =item B<-CRLform> B<DER>|B<PEM> The CRL file format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-crl_download> @@ -278,13 +278,13 @@ If not specified then the certificate file will be used to read also the key. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-pass> I<arg> the private key and certifiate file password source. For more information about the format of I<arg> -see L<openssl(1)/Pass phrase options>. +see L<openssl-passphrase-options(1)/Pass phrase options>. =item B<-verify> I<depth> diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index e568fbab0a..23693956a2 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -261,13 +261,13 @@ The private Key file to use for servername if not given via B<-cert2>. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-pass> I<val> The private key and certificate file password source. For more information about the format of I<val>, -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-dcert> I<infile>, B<-dkey> I<filename>|I<uri> @@ -296,13 +296,13 @@ This option has no effect and is retained for backward compatibility only. The format of the additional private key; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options>. +See L<openssl-format-options(1)/Format Options>. =item B<-dpass> I<val> The passphrase for the additional private key and certificate. For more information about the format of I<val>, -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-nbio_test> @@ -335,7 +335,7 @@ The CRL file to use. =item B<-CRLform> B<DER>|B<PEM> The CRL file format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-crl_download> diff --git a/doc/man1/openssl-sess_id.pod.in b/doc/man1/openssl-sess_id.pod.in index 67cc0e7e2d..6af88b4c38 100644 --- a/doc/man1/openssl-sess_id.pod.in +++ b/doc/man1/openssl-sess_id.pod.in @@ -40,7 +40,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>|B<NSS> The input and output formats; the default is PEM. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. For B<NSS> output, the session ID and master key are reported in NSS "keylog" format. diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in index aa2dfaf8c5..563340b152 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -117,19 +117,19 @@ format message that has been signed or verified. The input format of the PKCS#7 (S/MIME) structure (if one is being read); the default is B<SMIME>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-outform> B<DER>|B<PEM>|B<SMIME> The output format of the PKCS#7 (S/MIME) structure (if one is being written); the default is B<SMIME>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-stream>, B<-indef>, B<-noindef> @@ -270,7 +270,7 @@ multiple times to specify successive keys. =item B<-passin> I<arg> The private key password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-to>, B<-from>, B<-subject> diff --git a/doc/man1/openssl-spkac.pod.in b/doc/man1/openssl-spkac.pod.in index 31df6b3b59..2a596ed314 100644 --- a/doc/man1/openssl-spkac.pod.in +++ b/doc/man1/openssl-spkac.pod.in @@ -62,12 +62,12 @@ present. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-passin> I<arg> The input file password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-challenge> I<string> diff --git a/doc/man1/openssl-srp.pod.in b/doc/man1/openssl-srp.pod.in index 930b128506..8a2730265f 100644 --- a/doc/man1/openssl-srp.pod.in +++ b/doc/man1/openssl-srp.pod.in @@ -70,7 +70,7 @@ adding or modifying a user. The password source for the input and output file. For more information about the format of B<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. {- $OpenSSL::safe::opt_engine_item -} diff --git a/doc/man1/openssl-storeutl.pod.in b/doc/man1/openssl-storeutl.pod.in index b831310695..404639e6fd 100644 --- a/doc/man1/openssl-storeutl.pod.in +++ b/doc/man1/openssl-storeutl.pod.in @@ -55,7 +55,7 @@ this option prevents output of the PEM data. =item B<-passin> I<arg> the key password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-text> diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index c74f71b10a..d91d06f0fd 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -336,8 +336,8 @@ all intermediate CA certificates unless the response includes them. =item B<-CAfile> I<file>, B<-CApath> I<dir>, B<-CAstore> I<uri> -See L<openssl(1)/Trusted Certificate Options> for details. -At least one of B<-CApath>, B<-CAfile> or B<-CAstore> must be specified. +See L<openssl-verification-options(1)/Trusted Certificate Options> for details. +At least one of B<-CAfile>, B<-CApath> or B<-CAstore> must be specified. {- $OpenSSL::safe::opt_v_item -} diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod new file mode 100644 index 0000000000..af1c7e3a43 --- /dev/null +++ b/doc/man1/openssl-verification-options.pod @@ -0,0 +1,453 @@ +=pod + +=head1 NAME + +openssl-verification-options - generic X.509 certificate verification options + +=head1 SYNOPSIS + +B<openssl> +I<command> +[ I<options> ... ] +[ I<parameters> ... ] + +=head1 DESCRIPTION + +Many OpenSSL commands and various other uses of the crypto library function +L<X509_verify_cert(3)> verify X.509 certificates. The details of how each +command handles errors are documented on the specific command page. + +Certificate verification is a complicated process, consisting of +a number of separate steps that are detailed in the following paragraphs. + +First, a certificate chain is built up starting from the target certificate +and typically ending in a self-signed "root" CA certificate. +It is an error if the whole chain cannot be built up +unless the B<-partial_chain> option is given. +The chain is built up iteratively, looking up in turn +the certificate of the signer ("issuer") of the current certificate. +If a certificate is found that appears to be its own issuer +it is assumed to be the self-signed root, which must be trusted. + +The process of looking up the issuer's certificate itself involves a number +of steps. +All available certificates with a subject name that matches the issuer +name of the current certificate are subject to further tests. +The relevant authority key identifier components of the current certificate +(if present) must match the subject key identifier (if present) +and issuer and serial number of the candidate issuer certificate. + +The lookup first searches for issuer certificates in the trust store. +If it does not find a match there it consults +the list of untrusted "intermediate" CA certificates (if provided). +The last certificate (which typically is of a root CA) is always looked up +in the trusted certificate list; an exact match must be found there. + +The second step is to check the extensions of every untrusted certificate +for consistency with the supplied purpose. +If the B<-purpose> option is not included then no checks are done. +The target or "leaf" certificate must have extensions compatible with the +supplied purpose and all other certificates must also be valid CA certificates. +The precise extensions required are described in more detail in +L<openssl-x509(1)/CERTIFICATE EXTENSIONS>. + +The third step is to check the trust settings on the last certficate, +typically of a root CA. +It should be trusted for the supplied purpose. +For compatibility with previous versions of OpenSSL, +a certificate with no trust settings is considered to be valid for all purposes. + +The fourth, and final, step is to check the validity of the certificate chain. +For each element in the chain, including the root CA certificate, +the validity period as specified by the C<notBefore> and C<notAfter> fields +is checked against the current system time. +The B<-attime> flag may be used to use a reference time other than "now." +The certificate signature is checked as well +(except for the signature of the typically self-signed root CA certificate, +which is verified only if the B<-check_ss_sig> option is given). +When verifying a certificate signature +the keyUsage extension (if present) of the candidate issuer certificate +is checked to permit digitalSignature for signing proxy certificates +or to permit keyCertSign for signing other certificates, respectively. +If all operations complete successfully then certificate is considered +valid. If any operation fails then the certificate is not valid. + +=head1 OPTIONS + +=head2 Trusted Certificate Options + +The following options specify how to select the trusted root certificates, +also known as trust anchors. +A collection of trusted roots is called a I<trust store>. + +Note that OpenSSL does not provide a default set of trust anchors. Many +Linux distributions include a system default and configure OpenSSL to point +to that. Mozilla maintains an influential trust store that can be found at +L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>. + +The certificates to trust can be specified using following options. + +=over 4 + +=item B<-CAfile> I<file> + +Load the specified file which contains one or more PEM-format certificates +of CA's that are trusted. + +=item B<-no-CAfile> + +Do not load the default file of trusted certificates. + +=item B<-CApath> I<dir> + +Use the specified directory as a list of trust certificates. That is, +files should be named with the hash of the X.509 SubjectName of each +certificate. This is so that the library can extract the IssuerName, +hash it, and directly lookup the file to get the issuer certificate. +See L<openssl-rehash(1)> for information on creating this type of directory. + +=item B<-no-CApath> + +Do not use the default directory of trusted certificates. + +=item B<-CAstore> I<uri> + +Use I<uri> as a store of trusted CA certificates. The URI may +indicate a single certificate, as well as a collection of them. +With URIs in the C<file:> scheme, this acts as B<-CAfile> or +B<-CApath>, depending on if the URI indicates a single file or +directory. +See L<ossl_store-file(7)> for more information on the C<file:> scheme. + +These certificates are also used when building the server certificate +chain (for example with L<openssl-s_server(1)>) or client certificate +chain (for example with L<openssl-s_time(1)>). + +=item B<-no-CAstore> + +Do not use the default store. + +=back + +=head2 Verification Options + +The certificate verification can be fine-tuned with the following flags. + +=over 4 + +=item B<-verbose> + +Print extra information about the operations being performed. + +=item B<-attime> I<timestamp> + +Perform validation checks using time specified by I<timestamp> and not +current system time. I<timestamp> is the number of seconds since +January 1, 1970 (i.e., the Unix Epoch). + +=item B<-no_check_time> + +This option suppresses checking the validity period of certificates and CRLs +against the current time. If option B<-attime> is used to specify +a verification time, the check is not suppressed. + +=item B<-x509_strict> + +This disables non-compliant workarounds for broken certificates. +Thus errors are thrown on certificates not compliant with RFC 5280. + +When this option is set, +among others, the following certificate well-formedness conditions are checked: + +=over 4 + +=item - + +The basicConstraints of CA certificates must be marked critical. + +=item - + +CA certificates must explicitly include the keyUsage extension. + +=item - + +If a pathlenConstraint is given the key usage keyCertSign must be allowed. + +=item - + +The pathlenConstraint must not be given for non-CA certificates. + +=item - + +The issuer name of any certificate must not be empty. + +=item - + +The subject name of CA certs, certs with keyUsage crlSign, and certs +without subjectAlternativeName must not be empty. + +=item - + +If a subjectAlternativeName extension is given it must not be empty. + +=item - + +The signatureAlgorithm field and the cert signature must be consistent. + +=item - + +Any given authorityKeyIdentifier and any given subjectKeyIdentifier +must not be marked critical. + +=item - + +The authorityKeyIdentifier must be given for X.509v3 certs unless they +are self-signed. + +=item - + +The subjectKeyIdentifier must be given for all X.509v3 CA certs. + +=back + +=item B<-ignore_critical> + +Normally if an unhandled critical extension is present that is not +supported by OpenSSL the certificate is rejected (as required by RFC5280). +If this option is set critical extensions are ignored. + +=item B<-issuer_checks> + +Ignored. + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-crl_check_all> + +Checks the validity of B<all> certificates in the chain by attempting +to look up valid CRLs. + +=item B<-use_deltas> + +Enable support for delta CRLs. + +=item B<-extended_crl> + +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. + +=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> + +Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or +192 bit, or only 192 bit Level of Security respectively. +See RFC6460 for details. In particular the supported signature algorithms are +reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves +P-256 and P-384. + +=item B<-auth_level> I<level> + +Set the certificate chain authentication security level to I<level>. +The authentication security level determines the acceptable signature and +public key strength when verifying certificate chains. For a certificate +chain to validate, the public keys of all the certificates must meet the +specified security I<level>. The signature algorithm security level is +enforced for all the certificates in the chain except for the chain's +I<trust anchor>, which is either directly trusted or validated by means +other than its signature. See L<SSL_CTX_set_security_level(3)> for the +definitions of the available levels. The default security level is -1, +or "not set". At security level 0 or lower all algorithms are acceptable. +Security level 1 requires at least 80-bit-equivalent security and is broadly +interoperable, though it will, for example, reject MD5 signatures or RSA +keys shorter than 1024 bits. + +=item B<-partial_chain> + +Allow verification to succeed even if a I<complete> chain cannot be built to a +self-signed trust-anchor, provided it is possible to construct a chain to a +trusted certificate that might not be self-signed. +This certificate may be self-issued or belong to an intermediate CA. + +=item B<-check_ss_sig> + +Verify the signature of +the last certificate in a chain if the certificate is supposedly self-signed. +This is prohibited and will result in an error if it is a non-conforming CA +certificate with key usage restrictions not including the keyCertSign bit. +This verification is disabled by default because it doesn't add any security. + +=item B<-allow_proxy_certs> + +Allow the verification of proxy certificates. + +=item B<-trusted_first> + +As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. + +When constructing the certificate chain, the trusted certificates specified +via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> are always used +before any certificates specified via B<-untrusted>. + +=item B<-no_alt_chains> + +As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no +effect. + +=item B<-trusted> I<file> + +Parse I<file> as a set of one or more certificates in PEM format. +All certificates must be self-signed, unless the +B<-partial_chain> option is specified. +This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options +and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so +only certificates in the file are trust anchors. +This option may be used multiple times. + +=item B<-untrusted> I<file> + +Parse I<file> as a set of one or more certificates in PEM format. +All certificates are untrusted certificates (typically of intermedate CAs) +that may be used to +construct a certificate chain from the subject certificate to a trust anchor. +This option may be used multiple times. + +=item B<-policy> I<arg> + +Enable policy processing and add I<arg> to the user-initial-policy-set (see +RFC5280). The policy I<arg> can be an object name an OID in numeric form. +This argument can appear more than once. + +=item B<-explicit_policy> + +Set policy variable require-explicit-policy (see RFC5280). + +=item B<-policy_check> + +Enables certificate policy processing. + +=item B<-policy_print> + +Print out diagnostics related to policy processing. + +=item B<-inhibit_any> + +Set policy variable inhibit-any-policy (see RFC5280). + +=item B<-inhibit_map> + +Set policy variable inhibit-policy-mapping (see RFC5280). + +=item B<-purpose> I<purpose> + +The intended use for the certificate. If this option is not specified, this +command will not consider certificate purpose during chain verification. +Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, +B<smimesign>, B<smimeencrypt>. + +=item B<-verify_depth> I<num> + +Limit the certificate chain to I<num> intermediate CA certificates. +A maximal depth chain can have up to I<num>+2 certificates, since neither the +end-entity certificate nor the trust-anchor certificate count against the +B<-verify_depth> limit. + +=item B<-verify_email> I<email> + +Verify if I<email> matches the email address in Subject Alternative Name or +the email in the subject Distinguished Name. + +=item B<-verify_hostname> I<hostname> + +Verify if I<hostname> matches DNS name in Subject Alternative Name or +Common Name in the subject certificate. + +=item B<-verify_ip> I<ip> + +Verify if I<ip> matches the IP address in Subject Alternative Name of +the subject certificate. + +=item B<-verify_name> I<name> + +Use default verification policies like trust model and required certificate +policies identified by I<name>. +The trust model determines which auxiliary trust or reject OIDs are applicable +to verifying the given certificate chain. +See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>. +Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>, +B<ssl_client>, B<ssl_server>. +These mimics the combinations of purpose and trust settings used in SSL, CMS +and S/MIME. +As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not +specified, so the B<-verify_name> options are functionally equivalent to the +corresponding B<-purpose> settings. + +=back + +=head2 Extended Verification Options + +Sometimes there may be more than one certificate chain leading to an +end-entity certificate. +This usually happens when a root or intermediate CA signs a certificate +for another a CA in other organization. +Another reason is when a CA might have intermediates that use two different +signature formats, such as a SHA-1 and a SHA-256 digest. + +The following options can be used to provide data that will allow the +OpenSSL command to generate an alternative chain. + +=over 4 + +=item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain> + +Specify an extra certificate, private key and certificate chain. These behave +in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When +specified, the callback returning the first valid chain will be in use by the +client. + +=item B<-xchain_build> + +Specify whether the application should build the certificate chain to be +provided to the server for the extra certificates via the B<-xkey>, +B<-xcert>, and B<-xchain> options. + +=item B<-xcertform> B<DER>|B<PEM>|B<P12> + +The input format for the extra certificate. +This option has no effect and is retained for backward compatibility only. + +=item B<-xkeyform> B<DER>|B<PEM>|B<P12> + +The input format for the extra key. +This option has no effect and is retained for backward compatibility only. + +=back + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<openssl-verify(1)>, +L<openssl-ocsp(1)>, +L<openssl-ts(1)>, +L<openssl-s_client(1)>, +L<openssl-s_server(1)>, +L<openssl-smime(1)>, +L<openssl-cmp(1)>, +L<openssl-cms(1)> + + +=head1 HISTORY + +The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in index 9e3e49b2d7..2b5a350553 100644 --- a/doc/man1/openssl-verify.pod.in +++ b/doc/man1/openssl-verify.pod.in @@ -147,7 +147,7 @@ B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. =head1 SEE ALSO -L<openssl(1)>, +L<openssl-verification-options(1)>, L<openssl-x509(1)>, L<ossl_store-file(7)> diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in index ffa2ab4aed..a3f7639284 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/doc/man1/openssl-x509.pod.in @@ -101,7 +101,7 @@ Print out a usage message. =item B<-inform> B<DER>|B<PEM> The CSR input format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. The input is normally an X.509 certificate file of any format, but this can change if other options such as B<-req> are used. @@ -109,7 +109,7 @@ but this can change if other options such as B<-req> are used. B<-outform> B<DER>|B<PEM> The output format; the default is B<PEM>. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-in> I<filename> @@ -382,7 +382,7 @@ Names and values of these options are algorithm-specific. The key and certificate file password source. For more information about the format of I<arg> -see L<openssl(1)/Pass Phrase Options>. +see L<openssl-passphrase-options(1)/Pass Phrase Options>. =item B<-clrext> @@ -395,7 +395,7 @@ retained. The key format; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-CAform> B<DER>|B<PEM>|B<P12>, @@ -406,7 +406,7 @@ This option has no effect and is retained for backward compatibility. The format for the CA key; the default is B<PEM>. The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. +See L<openssl-format-options(1)/Format Options> for details. =item B<-days> I<arg> diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index ace96274f9..9daa13189e 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -304,6 +304,7 @@ Time Stamping Authority command. =item B<verify> X.509 Certificate Verification. +See also the L<openssl-verification-options(1)> manual page. =item B<version> @@ -522,215 +523,11 @@ parameters start with a minus sign: =head2 Format Options -Several OpenSSL commands can take input or generate output in a variety -of formats. -Since OpenSSL 3.0 keys, single certificates, and CRLs can be read from -files in any of the B<DER>, B<PEM> or B<P12> formats, -while specifying their input format is no more needed. -In order to access a key via an engine the input format B<ENGINE> may be used; -alternatively the key identifier in the <uri> argument of the respective key -option may be preceded by C<org.openssl.engine:>. -See L<openssl(1)/Engine Options> for an example usage of the latter. - -The list of acceptable formats, and the default, is -described in each command documentation. The list of formats is -described below. Both uppercase and lowercase are accepted. - -=over 4 - -=item B<DER> - -A binary format, encoded or parsed according to Distinguished Encoding Rules -(DER) of the ASN.1 data language. - -=item B<ENGINE> - -Used to specify that the cryptographic material is in an OpenSSL B<engine>. -An engine must be configured or specified using the B<-engine> option. -A password or PIN may be supplied to the engine using the B<-passin> option. - -=item B<P12> - -A DER-encoded file containing a PKCS#12 object. -It might be necessary to provide a decryption password to retrieve -the private key. - -=item B<PEM> - -A text format defined in IETF RFC 1421 and IETF RFC 7468. Briefly, this is -a block of base-64 encoding (defined in IETF RFC 4648), with specific -lines used to mark the start and end: - - Text before the BEGIN line is ignored. - ----- BEGIN object-type ----- - OT43gQKBgQC/2OHZoko6iRlNOAQ/tMVFNq7fL81GivoQ9F1U0Qr+DH3ZfaH8eIkX - xT0ToMPJUzWAn8pZv0snA0um6SIgvkCuxO84OkANCVbttzXImIsL7pFzfcwV/ERK - UM6j0ZuSMFOCr/lGPAoOQU0fskidGEHi1/kW+suSr28TqsyYZpwBDQ== - ----- END object-type ----- - Text after the END line is also ignored - -The I<object-type> must match the type of object that is expected. -For example a C<BEGIN X509 CERTIFICATE> will not match if the command -is trying to read a private key. The types supported include: - - ANY PRIVATE KEY - CERTIFICATE - CERTIFICATE REQUEST - CMS - DH PARAMETERS - DSA PARAMETERS - DSA PUBLIC KEY - EC PARAMETERS - EC PRIVATE KEY - ECDSA PUBLIC KEY - ENCRYPTED PRIVATE KEY - PARAMETERS - PKCS #7 SIGNED DATA - PKCS7 - PRIVATE KEY - PUBLIC KEY - RSA PRIVATE KEY - SSL SESSION PARAMETERS - TRUSTED CERTIFICATE - X509 CRL - X9.42 DH PARAMETERS - -The following legacy I<object-type>'s are also supported for compatibility -with earlier releases: - - DSA PRIVATE KEY - NEW CERTIFICATE REQUEST - RSA PUBLIC KEY - X509 CERTIFICATE - -=item B<SMIME> - -An S/MIME object as described in IETF RFC 8551. -Earlier versions were known as CMS and are compatible. -Note that the parsing is simple and might fail to parse some legal data. - -=back - -The options to specify the format are as follows. Refer to the individual -man page to see which options are accepted. - -=over 4 - -=item B<-inform> I<format>, B<-outform> I<format> - -The format of the input or output streams. - -=item B<-keyform> I<format> - -Format of a private key input source. -The only value with effect is B<ENGINE>; all others have become obsolete. -See L<openssl(1)/Format Options> for details. - -=item B<-CRLform> I<format> - -Format of a CRL input source. - -=back +See L<openssl-format-options(1)> for manual page. =head2 Pass Phrase Options -Several commands accept password arguments, typically using B<-passin> -and B<-passout> for input and output passwords respectively. These allow -the password to be obtained from a variety of sources. Both of these -options take a single argument whose format is described below. If no -password argument is given and a password is required then the user is -prompted to enter one: this will typically be read from the current -terminal with echoing turned off. - -Note that character encoding may be relevant, please see -L<passphrase-encoding(7)>. - -=over 4 - -=item B<pass:>I<password> - -The actual password is I<password>. Since the password is visible -to utilities (like 'ps' under Unix) this form should only be used -where security is not important. - -=item B<env:>I<var> - -Obtain the password from the environment variable I<var>. Since -the environment of other processes is visible on certain platforms -(e.g. ps under certain Unix OSes) this option should be used with caution. - -=item B<file:>I<pathname> - -The first line of I<pathname> is the password. If the same I<pathname> -argument is supplied to B<-passin> and B<-passout> arguments then the first -line will be used for the input password and the next line for the output -password. I<pathname> need not refer to a regular file: it could for example -refer to a device or named pipe. - -=item B<fd:>I<number> - -Read the password from the file descriptor I<number>. This can be used to -send the data via a pipe for example. - -=item B<stdin> - -Read the password from standard input. - -=back - -=head2 Trusted Certificate Options - -Part of validating a certificate includes verifying that the chain of CA's -can be traced up to an existing trusted root. The following options specify -how to list the trusted roots, also known as trust anchors. A collection -of trusted roots is called a I<trust store>. - -Note that OpenSSL does not provide a default set of trust anchors. Many -Linux distributions include a system default and configure OpenSSL to point -to that. Mozilla maintains an influential trust store that can be found at -L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>. - -=over 4 - -=item B<-CAfile> I<file> - -Load the specified file which contains one or more PEM-format certificates -of CA's that are trusted. - -=item B<-no-CAfile> - -Do not load the default file of trusted certificates. - -=item B<-CApath> I<dir> - -Use the specified directory as a list of trust certificates. That is, -files should be named with the hash of the X.509 SubjectName of each -certificate. This is so that the library can extract the IssuerName, -hash it, and directly lookup the file to get the issuer certificate. -See L<openssl-rehash(1)> for information on creating this type of directory. - -=item B<-no-CApath> - -Do not use the default directory of trusted certificates. - -=item B<-CAstore> I<uri> - -Use I<uri> as a store of trusted CA certificates. The URI may -indicate a single certificate, as well as a collection of them. -With URIs in the C<file:> scheme, this acts as B<-CAfile> or -B<-CApath>, depending on if the URI indicates a single file or -directory. -See L<ossl_store-file(7)> for more information on the C<file:> scheme. - -These certificates are also used when building the server certificate -chain (for example with L<openssl-s_server(1)>) or client certificate -chain (for example with L<openssl-s_time(1)>). - -=item B<-no-CAstore> - -Do not use the default store. - -=back +See the L<openssl-passphrase-options(1)> manual page. =head2 Random State Options @@ -762,509 +559,13 @@ This file can be used in a subsequent command invocation. =back -=head2 Extended Verification Options - -Sometimes there may be more than one certificate chain leading to an -end-entity certificate. -This usually happens when a root or intermediate CA signs a certificate -for another a CA in other organization. -Another reason is when a CA might have intermediates that use two different -signature formats, such as a SHA-1 and a SHA-256 digest. - -The following options can be used to provide data that will allow the -OpenSSL command to generate an alternative chain. - -=over 4 - -=item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain> - -Specify an extra certificate, private key and certificate chain. These behave -in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When -specified, the callback returning the first valid chain will be in use by the -client. - -=item B<-xchain_build> - -Specify whether the application should build the certificate chain to be -provided to the server for the extra certificates via the B<-xkey>, -B<-xcert>, and B<-xchain> options. - -=item B<-xcertform> B<DER>|B<PEM>|B<P12> - -The input format for the extra certificate. -This option has no effect and is retained for backward compatibility only. - -=item B<-xkeyform> B<DER>|B<PEM>|B<P12> - -The input format for the extra key. -This option has no effect and is retained for backward compatibility only. - -=back - -=head2 Verification Options - -Many OpenSSL commands verify certificates. The details of how each -command handles errors are documented on the specific command page. - -Verification is a complicated process, consisting of a number of separate -steps that are detailed in the following paragraphs. - -First, a certificate chain is built up starting from the target certificate -and typically ending in a self-signed "root" CA certificate. -It is an error if the whole chain cannot be built up -unless the B<-partial_chain> option is given. -The chain is built up iteratively, looking up in turn -the certificate of the signer ("issuer") of the current certificate. -If a certificate is found that appears to be its own issuer -it is assumed to be the self-signed root, which must be trusted. - -The process of looking up the issuer's certificate itself involves a number -of steps. -All available certificates with a subject name that matches the issuer -name of the current certificate are subject to further tests. -The relevant authority key identifier components of the current certificate -(if present) must match the subject key identifier (if present) -and issuer and serial number of the candidate issuer certificate. - -The lookup first searches for issuer certificates in the trust store. -If it does not find a match there it consults -the list of untrusted "intermediate" CA certificates (if provided). -The last certificate (which typically is of a root CA) is always looked up -in the trusted certificate list; an exact match must be found there. - -The second step is to check the extensions of every untrusted certificate -for consistency with the supplied purpose. -If the B<-purpose> option is not included then no checks are done. -The target or "leaf" certificate must have extensions compatible with the -supplied purpose and all other certificates must also be valid CA certificates. -The precise extensions required are described in more detail in -L<openssl-x509(1)/CERTIFICATE EXTENSIONS>. - -The third step is to check the trust settings on the last certficate, -typically of a root CA. -It should be trusted for the supplied purpose. -For compatibility with previous versions of OpenSSL, -a certificate with no trust settings is considered to be valid for all purposes. - -The fourth, and final, step is to check the validity of the certificate chain. -For each element in the chain, including the root CA certificate, -the validity period as specified by the C<notBefore> and C<notAfter> fields -is checked against the current system time. -The B<-attime> flag may be used to use a reference time other than "now." -The certificate signature is checked as well -(except for the signature of the typically self-signed root CA certificate, -which is verified only if the B<-check_ss_sig> option is given). -When verifying a certificate signature -the keyUsage extension (if present) of the candidate issuer certificate -is checked to permit digitalSignature for signing proxy certificates -or to permit keyCertSign for signing other certificates, respectively. -If all operations complete successfully then certificate is considered -valid. If any operation fails then the certificate is not valid. - -The details of the processing steps can be fine-tuned with the -following flags. - -=over 4 - -=item B<-verbose> - -Print extra information about the operations being performed. - -=item B<-attime> I<timestamp> - -Perform validation checks using time specified by I<timestamp> and not -current system time. I<timestamp> is the number of seconds since -January 1, 1970 (i.e., the Unix Epoch). - -=item B<-no_check_time> - -This option suppresses checking the validity period of certificates and CRLs -against the current time. If option B<-attime> is used to specify -a verification time, the check is not suppressed. - -=item B<-x509_strict> - -This disables non-compliant workarounds for broken certificates. -Thus errors are thrown on certificates not compliant with RFC 5280. - -When this option is set, -among others, the following certificate well-formedness conditions are checked: - -=over 4 - -=item - - -The basicConstraints of CA certificates must be marked critical. - -=item - - -CA certificates must explicitly include the keyUsage extension. - -=item - - -If a pathlenConstraint is given the key usage keyCertSign must be allowed. - -=item - - -The pathlenConstraint must not be given for non-CA certificates. - -=item - - -The issuer name of any certificate must not be empty. - -=item - - -The subject name of CA certs, certs with keyUsage crlSign, and certs -without subjectAlternativeName must not be empty. - -=item - - -If a subjectAlternativeName extension is given it must not be empty. - -=item - - -The signatureAlgorithm field and the cert signature must be consistent. - -=item - - -Any given authorityKeyIdentifier and any given subjectKeyIdentifier -must not be marked critical. - -=item - - -The authorityKeyIdentifier must be given for X.509v3 certs unless they -are self-signed. - -=item - - -The subjectKeyIdentifier must be given for all X.509v3 CA certs. - -=back - -=item B<-ignore_critical> - -Normally if an unhandled critical extension is present that is not -supported by OpenSSL the certificate is rejected (as required by RFC5280). -If this option is set critical extensions are ignored. - -=item B<-issuer_checks> - -Ignored. - -=item B<-crl_check> - -Checks end entity certificate validity by attempting to look up a valid CRL. -If a valid CRL cannot be found an error occurs. - -=item B<-crl_check_all> - -Checks the validity of B<all> certificates in the chain by attempting -to look up valid CRLs. - -=item B<-use_deltas> - -Enable support for delta CRLs. - -=item B<-extended_crl> - -Enable extended CRL features such as indirect CRLs and alternate CRL -signing keys. - -=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> - -Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or -192 bit, or only 192 bit Level of Security respectively. -See RFC6460 for details. In particular the supported signature algorithms are -reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves -P-256 and P-384. - -=item B<-auth_level> I<level> - -Set the certificate chain authentication security level to I<level>. -The authentication security level determines the acceptable signature and -public key strength when verifying certificate chains. For a certificate -chain to validate, the public keys of all the certificates must meet the -specified security I<level>. The signature algorithm security level is -enforced for all the certificates in the chain except for the chain's -I<trust anchor>, which is either directly trusted or validated by means -other than its signature. See L<SSL_CTX_set_security_level(3)> for the -definitions of the available levels. The default security level is -1, -or "not set". At security level 0 or lower all algorithms are acceptable. -Security level 1 requires at least 80-bit-equivalent security and is broadly -interoperable, though it will, for example, reject MD5 signatures or RSA -keys shorter than 1024 bits. - -=item B<-partial_chain> - -Allow verification to succeed even if a I<complete> chain cannot be built to a -self-signed trust-anchor, provided it is possible to construct a chain to a -trusted certificate that might not be self-signed. -This certificate may be self-issued or belong to an intermediate CA. - -=item B<-check_ss_sig> - -Verify the signature of -the last certificate in a chain if the certificate is supposedly self-signed. -This is prohibited and will result in an error if it is a non-conforming CA -certificate with key usage restrictions not including the keyCertSign bit. -This verification is disabled by default because it doesn't add any security. - -=item B<-allow_proxy_certs> - -Allow the verification of proxy certificates. - -=item B<-trusted_first> - -As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. - -When constructing the certificate chain, the trusted certificates specified -via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> are always used -before any certificates specified via B<-untrusted>. - -=item B<-no_alt_chains> - -As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no -effect. - -=item B<-trusted> I<file> - -Parse I<file> as a set of one or more certificates in PEM format. -All certificates must be self-signed, unless the -B<-partial_chain> option is specified. -This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options -and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so -only certificates in the file are trust anchors. -This option may be used multiple times. - -=item B<-untrusted> I<file> - -Parse I<file> as a set of one or more certificates in PEM format. -All certificates are untrusted certificates (typically of intermedate CAs) -that may be used to -construct a certificate chain from the subject certificate to a trust anchor. -This option may be used multiple times. - -=item B<-policy> I<arg> - -Enable policy processing and add I<arg> to the user-initial-policy-set (see -RFC5280). The policy I<arg> can be an object name an OID in numeric form. -This argument can appear more than once. - -=item B<-explicit_policy> - -Set policy variable require-explicit-policy (see RFC5280). - -=item B<-policy_check> - -Enables certificate policy processing. - -=item B<-policy_print> - -Print out diagnostics related to policy processing. - -=item B<-inhibit_any> - -Set policy variable inhibit-any-policy (see RFC5280). - -=item B<-inhibit_map> - -Set policy variable inhibit-policy-mapping (see RFC5280). - -=item B<-purpose> I<purpose> - -The intended use for the certificate. If this option is not specified, this -command will not consider certificate purpose during chain verification. -Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, -B<smimesign>, B<smimeencrypt>. - -=item B<-verify_depth> I<num> - -Limit the certificate chain to I<num> intermediate CA certificates. -A maximal depth chain can have up to I<num>+2 certificates, since neither the -end-entity certificate nor the trust-anchor certificate count against the -B<-verify_depth> limit. - -=item B<-verify_email> I<email> - -Verify if I<email> matches any email address in a Subject Alternative Name or -(if no SAN is included) the email address in the subject Distinguished Name. - -=item B<-verify_hostname> I<hostname> - -Verify if I<hostname> matches any DNS name in a Subject Alternative Name or -(if no SAN is included) the Common Name in the subject Distinguished Name. +=head2 Certificate Verification Options -=item B<-verify_ip> I<ip> - -Verify if I<ip> matches any IP address in a Subject Alternative Name or -(if no SAN is included) the Common Name in the subject Distinguished Name. - -=item B<-verify_name> I<name> - -Use default verification policies like trust model and required certificate -policies identified by I<name>. -The trust model determines which auxiliary trust or reject OIDs are applicable -to verifying the given certificate chain. -See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>. -Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>, -B<ssl_client>, B<ssl_server>. -These mimics the combinations of purpose and trust settings used in SSL, CMS -and S/MIME. -As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not -specified, so the B<-verify_name> options are functionally equivalent to the -corresponding B<-purpose> settings. - -=back +See the L<openssl-verification-options(1)> manual page. =head2 Name Format Options -OpenSSL provides fine-grain control over how the subject and issuer DN's are -displayed. -This is specified by using the B<-nameopt> option, which takes a -comma-separated list of options from the following set. -An option may be preceded by a minus sign, C<->, to turn it off. -The default value is C<oneline>. -The first four are the most commonly used. - -=over 4 - -=item B<compat> - -Display the name using an old format from previous OpenSSL versions. - -=item B<RFC2253> - -Display the name using the format defined in RFC 2253. -It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, -B<dump_nostr>, B<dump_unknown>, B<dump_der>, B<sep_comma_plus>, B<dn_rev> -and B<sname>. - -=item B<oneline> - -Display the name in one line, using a format that is more readable -RFC 2253. -It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, -B<dump_nostr>, B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, -B<space_eq> and B<sname> options. - -=item B<multiline> - -Display the name using multiple lines. -It is equivalent to B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, B<space_eq>, -B<lname> and B<align>. - -=item B<esc_2253> - -Escape the "special" characters in a field, as required by RFC 2253. -That is, any of the characters C<,+"E<lt>E<gt>;>, C<#> at the beginning of -a string and leading or trailing spaces. - -=item B<esc_2254> - -Escape the "special" characters in a field as required by RFC 2254 in a field. -That is, the B<NUL> character and of C<()*>. - -=item B<esc_ctrl> - -Escape non-printable ASCII characters, codes less than 0x20 (space) -or greater than 0x7F (DELETE). They are displayed using RFC 2253 C<\XX> -notation where B<XX> are the two hex digits representing the character value. - -=item B<esc_msb> - -Escape any characters with the most significant bit set, that is with -values larger than 127, as described in B<esc_ctrl>. - -=item B<use_quote> - -Escapes some characters by surrounding the entire string with quotation -marks, C<">. -Without this option, individual special characters are preceded with -a backslash character, C<\>. - -=item B<utf8> - -Convert all strings to UTF-8 format first as required by RFC 2253. -If the output device is UTF-8 compatible, then using this option (and -not setting B<esc_msb>) may give the correct display of multibyte -characters. -If this option is not set, then multibyte characters larger than 0xFF -will be output as C<\UXXXX> for 16 bits or C<\WXXXXXXXX> for 32 bits. -In addition, any UTF8Strings will be converted to their character form first. - -=item B<ignore_type> - -This option does not attempt to interpret multibyte characters in any -way. That is, the content octets are merely dumped as though one octet -represents each character. This is useful for diagnostic purposes but -will result in rather odd looking output. - -=item B<show_type> - -Display the type of the ASN1 character string before the value, -such as C<BMPSTRING: Hello World>. - -=item B<dump_der> - -Any fields that would be output in hex format are displayed using -the DER encoding of the field. -If not set, just the content octets are displayed. -Either way, the B<#XXXX...> format of RFC 2253 is used. - -=item B<dump_nostr> - -Dump non-character strings, such as ASN.1 B<OCTET STRING>. -If this option is not set, then non character string types will be displayed -as though each content octet represents a single character. - -=item B<dump_all> - -Dump all fields. When this used with B<dump_der>, this allows the -DER encoding of the structure to be unambiguously determined. - -=item B<dump_unknown> - -Dump any field whose OID is not recognised by OpenSSL. - -=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, -B<sep_multiline> - -Specify the field separators. The first word is used between the -Relative Distinguished Names (RDNs) and the second is between -multiple Attribute Value Assertions (AVAs). Multiple AVAs are -very rare and their use is discouraged. -The options ending in "space" additionally place a space after the separator to make it more readable. -The B<sep_multiline> starts each field on its own line, and uses "plus space" -for the AVA separator. -It also indents the fields by four characters. -The default value is B<sep_comma_plus_space>. - -=item B<dn_rev> - -Reverse the fields of the DN as required by RFC 2253. -This also reverses the order of multiple AVAs in a field, but this is -permissible as there is no ordering on values. - -=item B<nofname>, B<sname>, B<lname>, B<oid> - -Specify how the field name is displayed. -B<nofname> does not display the field at all. -B<sname> uses the "short name" form (CN for commonName for example). -B<lname> uses the long form. -B<oid> represents the OID in numerical form and is useful for -diagnostic purpose. - -=item B<align> - -Align field values for a more readable output. Only usable with -B<sep_multiline>. - -=item B<space_eq> - -Places spaces round the equal sign, C<=>, character which follows the field -name. - -=back +See the L<openssl-namefmt-options(1)> manual page. =head2 TLS Version Options diff --git a/doc/man3/X509_verify_cert.pod b/doc/man3/X509_verify_cert.pod index 9dedcbc987..764e4df28e 100644 --- a/doc/man3/X509_verify_cert.pod +++ b/doc/man3/X509_verify_cert.pod @@ -21,7 +21,7 @@ a set of non-trusted certificates that may be needed for chain construction, flags such as X509_V_FLAG_X509_STRICT, and various other optional components such as a callback function that allows customizing the verification outcome. A complete description of the certificate verification process is contained in -the L<openssl-verify(1)> manual page. +the L<openssl-verification-options(1)> manual page. Applications rarely call this function directly but it is used by OpenSSL internally for certificate validation, in both the S/MIME and diff --git a/doc/perlvars.pm b/doc/perlvars.pm index 56e53619e3..c13e224197 100644 --- a/doc/perlvars.pm +++ b/doc/perlvars.pm @@ -53,7 +53,7 @@ $OpenSSL::safe::opt_v_item = "" . "B<-verify_ip>, B<-verify_name>, B<-x509_strict> B<-issuer_checks>\n" . "\n" . "Set various options of certificate chain verification.\n" -. "See L<openssl(1)/Verification Options> for details."; +. "See L<openssl-verification-options(1)/Verification Options> for details."; # Extended validation options. @@ -70,7 +70,7 @@ $OpenSSL::safe::opt_x_item = "" . "B<-xkeyform> B<DER>|B<PEM>\n" . "\n" . "Set extended certificate verification options.\n" -. "See L<openssl(1)/Extended Verification Options> for details."; +. "See L<openssl-verification-options(1)/Extended Verification Options> for details."; # Name output options $OpenSSL::safe::opt_name_synopsis = "" @@ -79,7 +79,7 @@ $OpenSSL::safe::opt_name_item = "" . "=item B<-nameopt> I<option>\n" . "\n" . "This specifies how the subject or issuer names are displayed.\n" -. "See L<openssl(1)/Name Format Options> for details."; +. "See L<openssl-namefmt-options(1)/Name Format Options> for details."; # Random State Options $OpenSSL::safe::opt_r_synopsis = "" @@ -134,7 +134,7 @@ $OpenSSL::safe::opt_trust_item = "" . "=item B<-CAfile> I<file>, B<-no-CAfile>, B<-CApath> I<dir>, B<-no-CApath>,\n" . "B<-CAstore> I<uri>, B<-no-CAstore>\n" . "\n" -. "See L<openssl(1)/Trusted Certificate Options> for details."; +. "See L<openssl-verification-options(1)/Trusted Certificate Options> for details."; # TLS Version Options $OpenSSL::safe::opt_versiontls_synopsis = "" diff --git a/util/find-doc-nits b/util/find-doc-nits index c311d792f2..6d8b7144df 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -1173,7 +1173,8 @@ if ( $opt_n ) { # If not given args, check that all man1 commands are named properly. if ( scalar @ARGV == 0 ) { foreach ( files(TAGS => [ 'public_manual', 'man1' ]) ) { - next if /CA.pl/ || /openssl\.pod/ || /tsget\.pod/; + next if /openssl\.pod/ + || /CA\.pl/ || /tsget\.pod/; # these commands are special cases err("$_ doesn't start with openssl-") unless /openssl-/; } }