Document the behavior of the -inform and related options

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15100)

CHANGES.md

@@ -51,6 +51,13 @@ OpenSSL 3.0
 
    *Shane Lontis*
 
+ * The openssl commands that read keys, certificates, and CRLs now
+   automatically detect the PEM or DER format of the input files so it is not
+   necessary to explicitly specify the input format anymore. However if the
+   input format option is used the specified format will be required.
+
+   *David von Oheimb, Richard Levitte, and Tomáš Mráz*
+
  * Added enhanced PKCS#12 APIs which accept a library context `OSSL_LIB_CTX`
    and (where relevant) a property query. Other APIs which handle PKCS#7 and
    PKCS#8 objects have also been enhanced where required. This includes:

doc/man1/openssl-ca.pod.in

@@ -114,8 +114,9 @@ signed by the CA.
 
 =item B<-inform> B<DER>|B<PEM>
 
-The format of the data in certificate request input files.
-The default is PEM.
+The format of the data in certificate request input files;
+unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-ss_cert> I<filename>
 
@@ -150,8 +151,8 @@ The CA certificate, which must match with B<-keyfile>.
 
 =item B<-certform> B<DER>|B<PEM>|B<P12>
 
-The format of the data in certificate input files.
-This option has no effect and is retained for backward compatibility only.
+The format of the data in certificate input files; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-keyfile> I<filename>|I<uri>
 
@@ -160,8 +161,7 @@ This must match with B<-cert>.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-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.
+The format of the private key input file; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-sigopt> I<nm>:I<v>
@@ -818,11 +818,8 @@ retained mainly for compatibility reasons.
 
 The B<-section> option was added in OpenSSL 3.0.0.
 
-The B<-certform> and B<-multivalue-rdn> options
-have become obsolete in OpenSSL 3.0.0 and have no effect.
-
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
+The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
+has no effect.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 

doc/man1/openssl-cmp.pod.in

@@ -732,8 +732,7 @@ Default value is PEM.
 
 =item B<-keyform> I<PEM|DER|P12|ENGINE>
 
-The format of the key input.
-The only value with effect is B<ENGINE>.
+The format of the key input; unspecified by default.
 See L<openssl(1)/Format Options> for details.
 
 =item B<-otherpass> I<arg>

doc/man1/openssl-cms.pod.in

@@ -241,8 +241,7 @@ See L<openssl-format-options(1)> 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.
+The format of the private key file; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-rctform> B<DER>|B<PEM>|B<SMIME>
@@ -786,9 +785,6 @@ was added in OpenSSL 1.0.2.
 
 The -no_alt_chains option was added in OpenSSL 1.0.2b.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-nameopt> option was added in OpenSSL 3.0.0.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.

doc/man1/openssl-crl.pod.in

@@ -47,8 +47,8 @@ Print out a usage message.
 
 =item B<-inform> B<DER>|B<PEM>
 
-The CRL input format.
-This option has no effect and is retained for backward compatibility only.
+The CRL input format; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-outform> B<DER>|B<PEM>
 
@@ -61,8 +61,8 @@ The private key to be used to sign the CRL.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>
 
-The format of the private key file.
-This option has no effect and is retained for backward compatibility only.
+The format of the private key file; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-in> I<filename>
 
@@ -156,11 +156,6 @@ L<openssl-ca(1)>,
 L<openssl-x509(1)>,
 L<ossl_store-file(7)>
 
-=head1 HISTORY
-
-The B<-inform> and B<-keyform> options have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 =head1 COPYRIGHT
 
 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

doc/man1/openssl-dgst.pod.in

@@ -108,8 +108,7 @@ command instead for this.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-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.
+The format of the key to sign with; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-sigopt> I<nm>:I<v>
@@ -256,9 +255,6 @@ L<openssl-mac(1)>
 The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.
 The FIPS-related options were removed in OpenSSL 1.1.0.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> and B<-engine_impl> options were deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-dsa.pod.in

@@ -55,9 +55,14 @@ applications should use the more secure PKCS#8 format using the B<pkcs8>
 
 Print out a usage message.
 
-=item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
+=item B<-inform> B<DER>|B<PEM>
 
-The input and formats; the default is B<PEM>.
+The key input format; unspecified by default.
+See L<openssl-format-options(1)> for details.
+
+=item B<-outform> B<DER>|B<PEM>
+
+The key output format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
 Private keys are a sequence of B<ASN.1 INTEGERS>: the version (zero), B<p>,

doc/man1/openssl-dsaparam.pod.in

@@ -36,9 +36,14 @@ DSA parameters is often used to generate several distinct keys.
 
 Print out a usage message.
 
-=item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
+=item B<-inform> B<DER>|B<PEM>
 
-This option has become obsolete.
+The DSA parameters input format; unspecified by default.
+See L<openssl-format-options(1)> for details.
+
+=item B<-outform> B<DER>|B<PEM>
+
+The DSA parameters output format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
 Parameters are a sequence of B<ASN.1 INTEGER>s: B<p>, B<q>, and B<g>.

doc/man1/openssl-ec.pod.in

@@ -53,13 +53,12 @@ Print out a usage message.
 
 =item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The key input format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The key input format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-outform> B<DER>|B<PEM>
 
-The key output formats; the default is B<PEM>.
+The key output format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
 Private keys are an SEC1 private key or PKCS#8 format.

doc/man1/openssl-ecparam.pod.in

@@ -43,9 +43,14 @@ this command can only create EC parameters from known (named) curves.
 
 Print out a usage message.
 
-=item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
+=item B<-inform> B<DER>|B<PEM>
 
-The input and formats; the default is B<PEM>.
+The EC parameters input format; unspecified by default.
+See L<openssl-format-options(1)> for details.
+
+=item B<-outform> B<DER>|B<PEM>
+
+The EC parameters output format; the default is B<PEM>.
 See L<openssl-format-options(1)> for details.
 
 Parameters are encoded as B<EcpkParameters> as specified in IETF RFC 3279.

doc/man1/openssl-format-options.pod

@@ -15,9 +15,13 @@ I<command>
 
 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.
+files in any of the B<DER>, B<PEM> or B<P12> formats. Specifying their input
+format is no more needed and the openssl commands will automatically try all
+the possible formats. However if the B<DER> or B<PEM> input format is specified
+it will be enforced.
+
 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:>.
@@ -39,8 +43,6 @@ 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>
 

doc/man1/openssl-pkey.pod.in

@@ -78,8 +78,7 @@ a pass phrase will be prompted for.
 
 =item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The key input format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The key input format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-passin> I<arg>

doc/man1/openssl-pkeyutl.pod.in

@@ -91,8 +91,7 @@ The input key, by default it should be a private key.
 
 =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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-passin> I<arg>
@@ -106,8 +105,7 @@ The peer key file, used by key derivation (agreement) operations.
 
 =item B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The peer key format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The peer key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-pubin>
@@ -410,9 +408,6 @@ L<EVP_PKEY_CTX_set_tls1_prf_md(3)>,
 
 =head1 HISTORY
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-req.pod.in

@@ -74,7 +74,7 @@ Print out a usage message.
 
 =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
 
-The input and output formats; the default is B<PEM>.
+The input and output formats; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 The data is a PKCS#10 object.
@@ -197,8 +197,7 @@ It also accepts PKCS#8 format private keys for PEM format files.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The format of the private key; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The format of the private key; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-keyout> I<filename>
@@ -737,8 +736,8 @@ L<x509v3_config(5)>
 
 The B<-section> option was added in OpenSSL 3.0.0.
 
-All B<-keyform> values except B<ENGINE> and the B<-multivalue-rdn> option
-have become obsolete in OpenSSL 3.0.0 and have no effect.
+The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
+has no effect.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.

doc/man1/openssl-rsa.pod.in

@@ -60,8 +60,7 @@ Print out a usage message.
 
 =item B<-inform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The key input format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The key input format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-outform> B<DER>|B<PEM>

doc/man1/openssl-rsautl.pod.in

@@ -73,8 +73,7 @@ The input key, by default it should be an RSA private key.
 
 =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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-pubin>
@@ -231,9 +230,6 @@ L<openssl-genrsa(1)>
 
 This command was deprecated in OpenSSL 3.0.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-s_client.pod.in

@@ -243,8 +243,8 @@ The chain for the client certificate may be specified using B<-cert_chain>.
 
 =item B<-certform> B<DER>|B<PEM>|B<P12>
 
-The client certificate file format to use; the default is B<PEM>.
-This option has no effect and is retained for backward compatibility only.
+The client certificate file format to use; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-cert_chain>
 
@@ -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>.
+The CRL file format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-crl_download>
@@ -277,8 +277,7 @@ If not specified then the certificate file will be used to read also the key.
 
 =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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-pass> I<arg>
@@ -912,9 +911,6 @@ The B<-name> option was added in OpenSSL 1.1.1.
 
 The B<-certform> option has become obsolete in OpenSSL 3.0.0 and has no effect.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-s_server.pod.in

@@ -225,8 +225,8 @@ The certificate file to use for servername; default is C<server2.pem>.
 
 =item B<-certform> B<DER>|B<PEM>|B<P12>
 
-The server certificate file format.
-This option has no effect and is retained for backward compatibility only.
+The server certificate file format; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-cert_chain>
 
@@ -258,8 +258,7 @@ The private Key file to use for servername if not given via B<-cert2>.
 
 =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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-pass> I<val>
@@ -288,14 +287,13 @@ The input can be in PEM, DER, or PKCS#12 format.
 
 =item B<-dcertform> B<DER>|B<PEM>|B<P12>
 
-The format of the additional certificate file.
-This option has no effect and is retained for backward compatibility only.
+The format of the additional certificate file; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-dkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-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-format-options(1)>.
+The format of the additional private key; unspecified by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-dpass> I<val>
 
@@ -333,7 +331,7 @@ The CRL file to use.
 
 =item B<-CRLform> B<DER>|B<PEM>
 
-The CRL file format; the default is B<PEM>.
+The CRL file format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-crl_download>
@@ -844,12 +842,6 @@ The -no_alt_chains option was added in OpenSSL 1.1.0.
 The
 -allow-no-dhe-kex and -prioritize_chacha options were added in OpenSSL 1.1.1.
 
-All B<-keyform> and B<-dkeyform> values except B<ENGINE>
-have become obsolete in OpenSSL 3.0.0 and have no effect.
-
-The B<-certform> and B<-dcertform> options have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-smime.pod.in

@@ -127,8 +127,7 @@ See L<openssl-format-options(1)> 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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-stream>, B<-indef>, B<-noindef>
@@ -481,9 +480,6 @@ added in OpenSSL 1.0.0
 
 The -no_alt_chains option was added in OpenSSL 1.1.0.
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-spkac.pod.in

@@ -60,8 +60,7 @@ present.
 
 =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.
+The key format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-passin> I<arg>
@@ -150,9 +149,6 @@ L<openssl-ca(1)>
 
 =head1 HISTORY
 
-All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0
-and have no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man1/openssl-x509.pod.in

@@ -154,7 +154,7 @@ The B<-ext> option can be used to further restrict which extensions to copy.
 
 =item B<-inform> B<DER>|B<PEM>
 
-The CSR input file format; the default is B<PEM>.
+The input file format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-vfyopt> I<nm>:I<v>
@@ -181,8 +181,7 @@ This option is an alias of B<-key>.
 
 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The key input format; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The key input format; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-out> I<filename>
@@ -468,8 +467,8 @@ unless the B<-new> option is given, which generates a certificate from scratch.
 
 =item B<-CAform> B<DER>|B<PEM>|B<P12>,
 
-The format for the CA certificate.
-This option has no effect and is retained for backward compatibility.
+The format for the CA certificate; unspecifed by default.
+See L<openssl-format-options(1)> for details.
 
 =item B<-CAkey> I<filename>|I<uri>
 
@@ -479,8 +478,7 @@ If this option is not provided then the key must be present in the B<-CA> input.
 
 =item B<-CAkeyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 
-The format for the CA key; the default is B<PEM>.
-The only value with effect is B<ENGINE>; all others have become obsolete.
+The format for the CA key; unspecified by default.
 See L<openssl-format-options(1)> for details.
 
 =item B<-CAserial> I<filename>
@@ -879,11 +877,6 @@ form must have their links rebuilt using L<openssl-rehash(1)> or similar.
 The B<-signkey> option has been renamed to B<-key> in OpenSSL 3.0,
 keeping the old name as an alias.
 
-All B<-keyform> and B<-CAkeyform> values except B<ENGINE>
-have become obsolete in OpenSSL 3.0.0 and have no effect.
-
-The B<-CAform> option has become obsolete in OpenSSL 3.0.0 and has no effect.
-
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
 The B<-C> option was removed in OpenSSL 3.0.