From: Tomas Mraz Date: Mon, 3 May 2021 12:15:26 +0000 (+0200) Subject: Document the behavior of the -inform and related options X-Git-Tag: openssl-3.0.0-alpha16~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bee3f3890547cc7f349b69ef63665ebcc80d48ed;p=thirdparty%2Fopenssl.git Document the behavior of the -inform and related options Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/15100) --- diff --git a/CHANGES.md b/CHANGES.md index 5c696ff65ad..9d557c5c530 100644 --- a/CHANGES.md +++ b/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: diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in index 4e702f98c3d..3e2708ae04d 100644 --- a/doc/man1/openssl-ca.pod.in +++ b/doc/man1/openssl-ca.pod.in @@ -114,8 +114,9 @@ signed by the CA. =item B<-inform> B|B -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 for details. =item B<-ss_cert> I @@ -150,8 +151,8 @@ The CA certificate, which must match with B<-keyfile>. =item B<-certform> B|B|B -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 for details. =item B<-keyfile> I|I @@ -160,8 +161,7 @@ This must match with B<-cert>. =item B<-keyform> B|B|B|B -The format of the private key input file; the default is B. -The only value with effect is B; all others have become obsolete. +The format of the private key input file; unspecified by default. See L for details. =item B<-sigopt> I:I @@ -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 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. diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index f27443ca9c8..28ea4ee6a50 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -732,8 +732,7 @@ Default value is PEM. =item B<-keyform> I -The format of the key input. -The only value with effect is B. +The format of the key input; unspecified by default. See L for details. =item B<-otherpass> I diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 51aff981a5d..0ec906cbc11 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -241,8 +241,7 @@ See L for details. =item B<-keyform> B|B|B|B -The format of the private key file; the default is B. -The only value with effect is B; all others have become obsolete. +The format of the private key file; unspecified by default. See L for details. =item B<-rctform> B|B|B @@ -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 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. diff --git a/doc/man1/openssl-crl.pod.in b/doc/man1/openssl-crl.pod.in index ccba7938a2a..d00b80c8627 100644 --- a/doc/man1/openssl-crl.pod.in +++ b/doc/man1/openssl-crl.pod.in @@ -47,8 +47,8 @@ Print out a usage message. =item B<-inform> B|B -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 for details. =item B<-outform> B|B @@ -61,8 +61,8 @@ The private key to be used to sign the CRL. =item B<-keyform> B|B|B -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 for details. =item B<-in> I @@ -156,11 +156,6 @@ L, L, L -=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. diff --git a/doc/man1/openssl-dgst.pod.in b/doc/man1/openssl-dgst.pod.in index 4b0653912df..f493e83b418 100644 --- a/doc/man1/openssl-dgst.pod.in +++ b/doc/man1/openssl-dgst.pod.in @@ -108,8 +108,7 @@ command instead for this. =item B<-keyform> B|B|B|B -The format of the key to sign with; the default is B. -The only value with effect is B; all others have become obsolete. +The format of the key to sign with; unspecified by default. See L for details. =item B<-sigopt> I:I @@ -256,9 +255,6 @@ L 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 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 diff --git a/doc/man1/openssl-dsa.pod.in b/doc/man1/openssl-dsa.pod.in index 61f4b1f74bf..116121caf2c 100644 --- a/doc/man1/openssl-dsa.pod.in +++ b/doc/man1/openssl-dsa.pod.in @@ -55,9 +55,14 @@ applications should use the more secure PKCS#8 format using the B Print out a usage message. -=item B<-inform> B|B, B<-outform> B|B +=item B<-inform> B|B -The input and formats; the default is B. +The key input format; unspecified by default. +See L for details. + +=item B<-outform> B|B + +The key output format; the default is B. See L for details. Private keys are a sequence of B: the version (zero), B

, diff --git a/doc/man1/openssl-dsaparam.pod.in b/doc/man1/openssl-dsaparam.pod.in index 96c429cf940..64377074294 100644 --- a/doc/man1/openssl-dsaparam.pod.in +++ b/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|B, B<-outform> B|B +=item B<-inform> B|B -This option has become obsolete. +The DSA parameters input format; unspecified by default. +See L for details. + +=item B<-outform> B|B + +The DSA parameters output format; the default is B. See L for details. Parameters are a sequence of Bs: B

, B, and B. diff --git a/doc/man1/openssl-ec.pod.in b/doc/man1/openssl-ec.pod.in index 06c225f11cb..b3aabcb41af 100644 --- a/doc/man1/openssl-ec.pod.in +++ b/doc/man1/openssl-ec.pod.in @@ -53,13 +53,12 @@ Print out a usage message. =item B<-inform> B|B|B|B -The key input format; the default is B. -The only value with effect is B; all others have become obsolete. +The key input format; unspecified by default. See L for details. =item B<-outform> B|B -The key output formats; the default is B. +The key output format; the default is B. See L for details. Private keys are an SEC1 private key or PKCS#8 format. diff --git a/doc/man1/openssl-ecparam.pod.in b/doc/man1/openssl-ecparam.pod.in index ee5c0218190..dd8f0f2c24e 100644 --- a/doc/man1/openssl-ecparam.pod.in +++ b/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|B, B<-outform> B|B +=item B<-inform> B|B -The input and formats; the default is B. +The EC parameters input format; unspecified by default. +See L for details. + +=item B<-outform> B|B + +The EC parameters output format; the default is B. See L for details. Parameters are encoded as B as specified in IETF RFC 3279. diff --git a/doc/man1/openssl-format-options.pod b/doc/man1/openssl-format-options.pod index 20b62f9b15b..91058831cd8 100644 --- a/doc/man1/openssl-format-options.pod +++ b/doc/man1/openssl-format-options.pod @@ -15,9 +15,13 @@ I 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, B or B formats, -while specifying their input format is no more needed. +files in any of the B, B or B formats. Specifying their input +format is no more needed and the openssl commands will automatically try all +the possible formats. However if the B or B input format is specified +it will be enforced. + In order to access a key via an engine the input format B may be used; alternatively the key identifier in the argument of the respective key option may be preceded by C. @@ -39,8 +43,6 @@ The format of the input or output streams. =item B<-keyform> I Format of a private key input source. -The only value with effect is B; all others have become obsolete. -See L for details. =item B<-CRLform> I diff --git a/doc/man1/openssl-pkey.pod.in b/doc/man1/openssl-pkey.pod.in index 004be5c1322..d297b196380 100644 --- a/doc/man1/openssl-pkey.pod.in +++ b/doc/man1/openssl-pkey.pod.in @@ -78,8 +78,7 @@ a pass phrase will be prompted for. =item B<-inform> B|B|B|B -The key input format; the default is B. -The only value with effect is B; all others have become obsolete. +The key input format; unspecified by default. See L for details. =item B<-passin> I diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in index 26b9ed1e420..b57640992ce 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/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|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L for details. =item B<-passin> I @@ -106,8 +105,7 @@ The peer key file, used by key derivation (agreement) operations. =item B<-peerform> B|B|B|B -The peer key format; the default is B. -The only value with effect is B; all others have become obsolete. +The peer key format; unspecified by default. See L for details. =item B<-pubin> @@ -410,9 +408,6 @@ L, =head1 HISTORY -All B<-keyform> values except B have become obsolete in OpenSSL 3.0.0 -and have no effect. - The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in index a877140cdcc..32ae4b2e32a 100644 --- a/doc/man1/openssl-req.pod.in +++ b/doc/man1/openssl-req.pod.in @@ -74,7 +74,7 @@ Print out a usage message. =item B<-inform> B|B, B<-outform> B|B -The input and output formats; the default is B. +The input and output formats; unspecified by default. See L 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|B|B|B -The format of the private key; the default is B. -The only value with effect is B; all others have become obsolete. +The format of the private key; unspecified by default. See L for details. =item B<-keyout> I @@ -737,8 +736,8 @@ L The B<-section> option was added in OpenSSL 3.0.0. -All B<-keyform> values except B 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. diff --git a/doc/man1/openssl-rsa.pod.in b/doc/man1/openssl-rsa.pod.in index 1d98caabb64..503b31a6d6d 100644 --- a/doc/man1/openssl-rsa.pod.in +++ b/doc/man1/openssl-rsa.pod.in @@ -60,8 +60,7 @@ Print out a usage message. =item B<-inform> B|B|B|B -The key input format; the default is B. -The only value with effect is B; all others have become obsolete. +The key input format; unspecified by default. See L for details. =item B<-outform> B|B diff --git a/doc/man1/openssl-rsautl.pod.in b/doc/man1/openssl-rsautl.pod.in index 62c39eb69ed..a16c0bda152 100644 --- a/doc/man1/openssl-rsautl.pod.in +++ b/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|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L for details. =item B<-pubin> @@ -231,9 +230,6 @@ L This command was deprecated in OpenSSL 3.0. -All B<-keyform> values except B have become obsolete in OpenSSL 3.0.0 -and have no effect. - The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index e11df7a9ae6..33e8f313b60 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/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|B|B -The client certificate file format to use; the default is B. -This option has no effect and is retained for backward compatibility only. +The client certificate file format to use; unspecified by default. +See L for details. =item B<-cert_chain> @@ -263,7 +263,7 @@ CRL file to use to check the server's certificate. =item B<-CRLform> B|B -The CRL file format; the default is B. +The CRL file format; unspecified by default. See L 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|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L for details. =item B<-pass> I @@ -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 have become obsolete in OpenSSL 3.0.0 -and have no effect. - The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index fa4190a869a..f07e2ae3b48 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -225,8 +225,8 @@ The certificate file to use for servername; default is C. =item B<-certform> B|B|B -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 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|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L for details. =item B<-pass> I @@ -288,14 +287,13 @@ The input can be in PEM, DER, or PKCS#12 format. =item B<-dcertform> B|B|B -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 for details. =item B<-dkeyform> B|B|B|B -The format of the additional private key; the default is B. -The only value with effect is B; all others have become obsolete. -See L. +The format of the additional private key; unspecified by default. +See L for details. =item B<-dpass> I @@ -333,7 +331,7 @@ The CRL file to use. =item B<-CRLform> B|B -The CRL file format; the default is B. +The CRL file format; unspecified by default. See L 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 -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 diff --git a/doc/man1/openssl-smime.pod.in b/doc/man1/openssl-smime.pod.in index 3c5859dc01f..2fcf7020fe8 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -127,8 +127,7 @@ See L for details. =item B<-keyform> B|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L 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 have become obsolete in OpenSSL 3.0.0 -and have no effect. - The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man1/openssl-spkac.pod.in b/doc/man1/openssl-spkac.pod.in index f0ddd5179d4..3de862e0356 100644 --- a/doc/man1/openssl-spkac.pod.in +++ b/doc/man1/openssl-spkac.pod.in @@ -60,8 +60,7 @@ present. =item B<-keyform> B|B|B|B -The key format; the default is B. -The only value with effect is B; all others have become obsolete. +The key format; unspecified by default. See L for details. =item B<-passin> I @@ -150,9 +149,6 @@ L =head1 HISTORY -All B<-keyform> values except B have become obsolete in OpenSSL 3.0.0 -and have no effect. - The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man1/openssl-x509.pod.in b/doc/man1/openssl-x509.pod.in index 7f42d45cf78..0dcad3fd9b1 100644 --- a/doc/man1/openssl-x509.pod.in +++ b/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|B -The CSR input file format; the default is B. +The input file format; unspecified by default. See L for details. =item B<-vfyopt> I:I @@ -181,8 +181,7 @@ This option is an alias of B<-key>. =item B<-keyform> B|B|B|B -The key input format; the default is B. -The only value with effect is B; all others have become obsolete. +The key input format; unspecified by default. See L for details. =item B<-out> I @@ -468,8 +467,8 @@ unless the B<-new> option is given, which generates a certificate from scratch. =item B<-CAform> B|B|B, -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 for details. =item B<-CAkey> I|I @@ -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|B|B|B -The format for the CA key; the default is B. -The only value with effect is B; all others have become obsolete. +The format for the CA key; unspecified by default. See L for details. =item B<-CAserial> I @@ -879,11 +877,6 @@ form must have their links rebuilt using L 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 -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.