From 012353bdf21b98def920ac317b94c4a9ed501b79 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Wed, 30 Oct 2024 20:37:38 +0100 Subject: [PATCH] openssl-pkeyutl.pod.in: improve description of -rawin and -digest options Fixes #25827 Reviewed-by: Tomas Mraz Reviewed-by: Viktor Dukhovni (Merged from https://github.com/openssl/openssl/pull/25831) --- apps/pkeyutl.c | 5 ++- doc/man1/openssl-pkeyutl.pod.in | 68 ++++++++++++++++++++++----------- 2 files changed, 49 insertions(+), 24 deletions(-) diff --git a/apps/pkeyutl.c b/apps/pkeyutl.c index 34b3e47c80d53..2dc50c8a9014c 100644 --- a/apps/pkeyutl.c +++ b/apps/pkeyutl.c @@ -101,10 +101,11 @@ const OPTIONS pkeyutl_options[] = { OPT_SECTION("Output"), {"out", OPT_OUT, '>', "Output file - default stdout"}, {"secret", OPT_SECOUT, '>', "File to store secret on encapsulation"}, - {"asn1parse", OPT_ASN1PARSE, '-', "asn1parse the output data"}, + {"asn1parse", OPT_ASN1PARSE, '-', + "parse the output as ASN.1 data to check its DER encoding and print errors"}, {"hexdump", OPT_HEXDUMP, '-', "Hex dump output"}, {"verifyrecover", OPT_VERIFYRECOVER, '-', - "Verify with public key, recover original data"}, + "Verify RSA signature, recovering original signature input data"}, OPT_SECTION("Signing/Derivation/Encapsulation"), {"rawin", OPT_RAWIN, '-', diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in index e324656674443..3d512d9a3916b 100644 --- a/doc/man1/openssl-pkeyutl.pod.in +++ b/doc/man1/openssl-pkeyutl.pod.in @@ -65,24 +65,31 @@ if this option is not specified. =item B<-rawin> -This indicates that signature input data is raw data, which for most signature -algorithms (but not EdDSA) needs to be hashed by some message digest algorithm. -This option can only be used with B<-sign> and B<-verify> -and is implied by the Ed25519 and Ed448 algorithms. +This indicates that the signature or verification input data is raw data, +which is not hashed by any message digest algorithm. Except with EdDSA, the user can specify a digest algorithm by using the B<-digest> option. +For signature algorithms like RSA, DSA and ECDSA, +the default digest algorithm is SHA-256. For SM2, it is SM3. -The B<-digest> option implies B<-rawin>. +This option can only be used with B<-sign> and B<-verify>. +For EdDSA (the Ed25519 and Ed448 algorithms) this option +is implied since OpenSSL 3.5, and required in earlier versions. + +The B<-digest> option implies B<-rawin> since OpenSSL 3.5. =item B<-digest> I This option can only be used with B<-sign> and B<-verify>. -It specifies the digest algorithm which is used to hash the input data before -signing or verifying it with the input key. This option could be omitted if the -signature algorithm does not require one (for instance, EdDSA). If this option -is omitted but the signature algorithm requires one, a default value will be -used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the -default digest algorithm. For SM2, it will be SM3. +It specifies the digest algorithm that is used to hash the input data +before signing or verifying it with the input key. This option could be omitted +if the signature algorithm does not require preprocessing the input through +a pluggable hash function before signing (for instance, EdDSA). If this option +is omitted but the signature algorithm requires one and the B<-rawin> option +is given, a default value will be used (see B<-rawin> for details). +If this option is present, then the B<-rawin> option +is implied since OpenSSL 3.5, and required in earlier versions. + At this time, HashEdDSA (the ph or "prehash" variant of EdDSA) is not supported, so the B<-digest> option cannot be used with EdDSA. @@ -97,7 +104,7 @@ Specifies the output filename to write the secret to on I<-encap>. =item B<-sigfile> I -Signature file, required for B<-verify> operations only +Signature file, required and allowed for B<-verify> operations only =item B<-inkey> I|I @@ -141,20 +148,36 @@ This cannot be used in conjunction with B<-rawin>. =item B<-sign> Sign the input data and output the signed result. This requires a private key. -The input data given with the B<-in> option should be a hash value -unless the use of a message digest operation is implied, +Using a message digest operation along with this is recommended, +when applicable, see the B<-rawin> and B<-digest> options for details. +Otherwise, the input data given with the B<-in> option is assumed to already +be a digest, but this may then require an additional B<-pkeyopt> CI +in some cases (e.g., RSA with the default PKCS#1 padding mode). +Even for other algorithms like ECDSA, where the additional B<-pkeyopt> option +does not affect signature output, it is recommended, as it enables +checking that the input length is consistent with the intended digest. =item B<-verify> Verify the input data against the signature given with the B<-sigfile> option and indicate if the verification succeeded or failed. -The input data given with the B<-in> option should be a hash value -unless the use of a message digest operation is implied, +The input data given with the B<-in> option is assumed to be a hash value +unless the B<-rawin> option is specified or implied. +With raw data, when a digest algorithm is applicable, though it may be inferred +from the signature or take a default value, it should also be specified. =item B<-verifyrecover> -Verify the input data and output the recovered data. -The input data given with the B<-in> option should be a hash value. +Verify the given signature and output the recovered data (signature payload). +For example, in case of RSA PKCS#1 the recovered data is the B +DER encoding of the digest algorithm OID and value as specified in +L. + +Note that here the input given with the B<-in> option is not a signature input +(as with the B<-sign> and B<-verify> options) but a signature output value, +typically produced using the B<-sign> option. + +This option is available only for use with RSA keys. =item B<-encrypt> @@ -223,8 +246,9 @@ hex dump the output data. =item B<-asn1parse> -Parse the ASN.1 output data, this is useful when combined with the -B<-verifyrecover> option when an ASN1 structure is signed. +Parse the ASN.1 output data to check its DER encoding and print any errors. +When combined with the B<-verifyrecover> option, this may be useful only in case +an ASN.1 DER-encoded structure had been signed directly (without hashing it). {- $OpenSSL::safe::opt_engine_item -} @@ -248,8 +272,8 @@ engine I for crypto operations. The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below. -Unless otherwise mentioned all algorithms support the BI option -which specifies the digest in use for sign, verify and verifyrecover operations. +Unless otherwise mentioned, all algorithms support the BI option, +which specifies the digest in use for the signing and verification operations. The value I should represent a digest name as used in the EVP_get_digestbyname() function for example B. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the