4
0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-05-04 13:39:38 +00:00

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 <tmraz@fedoraproject.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/13315)
This commit is contained in:
Ankita Shetty 2020-11-27 17:05:30 +01:00 committed by Dr. David von Oheimb
parent b6f18ed2ef
commit ac093b3fe6
39 changed files with 531 additions and 428 deletions

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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.

@ -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>

@ -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.

@ -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>

@ -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

@ -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>

@ -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>>

@ -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>

@ -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

@ -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>

@ -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

@ -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>

@ -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.

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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>

@ -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.

@ -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>

@ -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>

@ -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 -}

@ -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>

@ -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 -}

@ -74,6 +74,61 @@ 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.

@ -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>

@ -523,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
@ -763,159 +559,13 @@ This file can be used in a subsequent command invocation.
=back
=head2 Verification Options
=head2 Certificate Verification Options
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

@ -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 = ""