GH554: Improve pkeyutl doc

[openssl.git] / doc / apps / pkeyutl.pod

diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod
index 1f7596da17307a003bc3edaeff3ca37dadddba0f..3c29b3a67c5afe602af066c80cc8ffcbe58687bb 100644 (file)
--- a/doc/apps/pkeyutl.pod
+++ b/doc/apps/pkeyutl.pod
@@ -59,7 +59,7 @@ the key format PEM, DER or ENGINE.
 =item B<-passin arg>
 
 the input key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 
 =item B<-peerkey file>
@@ -137,16 +137,30 @@ Unless otherwise mentioned all algorithms support the B<digest:alg> option
 which specifies the digest in use for sign, verify and verifyrecover operations.
 The value B<alg> should represent a digest name as used in the
 EVP_get_digestbyname() function for example B<sha1>.
+This value is used only for sanity-checking the lengths of data passed in to
+the B<pkeyutl> and for creating the structures that make up the signature
+(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
+In case of RSA, ECDSA and DSA signatures, this utility
+will not perform hashing on input data but rather use the data directly as
+input of signature algorithm. Depending on key type, signature type and mode
+of padding, the maximum acceptable lengths of input data differ. In general,
+with RSA the signed data can't be longer than the key modulus, in case of ECDSA
+and DSA the data shouldn't be longer than field size, otherwise it will be
+silently truncated to field size.
+
+In other words, if the value of digest is B<sha1> the input should be 20 bytes
+long binary encoding of SHA-1 hash function output.
 
 =head1 RSA ALGORITHM
 
-The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover
-operations in general. Some padding modes only support some of these 
-operations however.
+The RSA algorithm generally supports the encrypt, decrypt, sign,
+verify and verifyrecover operations. However, some padding modes
+support only a subset of these operations. The following additional
+B<pkeyopt> values are supported:
 
 =over 4
 
-=item -B<rsa_padding_mode:mode>
+=item B<rsa_padding_mode:mode>
 
 This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
 PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
@@ -218,5 +232,5 @@ Derive a shared secret value:
 
 =head1 SEE ALSO
 
-L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>
-L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
+L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
+L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>