mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-13 19:47:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

openssl-pkeyutl.pod.in: improve description of -rawin and -digest options

Browse Source 
Fixes #25827

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25831)
This commit is contained in:
Dr. David von Oheimb 2024-10-30 20:37:38 +01:00
parent 26a826c2d1
commit 012353bdf2
2 changed files with 49 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
apps/pkeyutl.c
View File

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

68
doc/man1/openssl-pkeyutl.pod.in
View File

@ -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<algorithm>
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<file>
Signature file, required for B<-verify> operations only
Signature file, required and allowed for B<-verify> operations only
=item B<-inkey> I<filename>|I<uri>
@ -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> C<digest:>I<md>
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<EMSA-PKCS-v1_5>
DER encoding of the digest algorithm OID and value as specified in
L<RFC8017 Section 9.2|https://datatracker.ietf.org/doc/html/rfc8017#section-9.2>.
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<id> 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 B<digest:>I<alg> option
which specifies the digest in use for sign, verify and verifyrecover operations.
Unless otherwise mentioned, all algorithms support the B<digest:>I<alg> option,
which specifies the digest in use for the signing and verification operations.
The value I<alg> should represent a digest name as used in the
EVP_get_digestbyname() function for example B<sha1>. This value is not used to
hash the input data. It is used (by some algorithms) for sanity-checking the