more doc fixes

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

diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod
index a7b75e6c756d7a03e372ef2ff18d1c31ca6420ab..a2da2558f6a9b84dd99fc0cc98c9aa8f8b0993d7 100644 (file)
--- a/doc/apps/pkeyutl.pod
+++ b/doc/apps/pkeyutl.pod
@@ -7,14 +7,15 @@ pkeyutl - public key algorithm utility
 =head1 SYNOPSIS
 
 B<openssl> B<pkeyutl>
+[B<-help>]
 [B<-in file>]
 [B<-out file>]
 [B<-sigfile file>]
 [B<-inkey file>]
-[B<-keyform PEM|DER>]
+[B<-keyform PEM|DER|ENGINE>]
 [B<-passin arg>]
 [B<-peerkey file>]
-[B<-peerform PEM|DER>]
+[B<-peerform PEM|DER|ENGINE>]
 [B<-pubin>]
 [B<-certin>]
 [B<-rev>]
@@ -28,6 +29,7 @@ B<openssl> B<pkeyutl>
 [B<-hexdump>]
 [B<-asn1parse>]
 [B<-engine id>]
+[B<-engine_impl>]
 
 =head1 DESCRIPTION
 
@@ -38,6 +40,10 @@ any supported algorithm.
 
 =over 4
 
+=item B<-help>
+
+Print out a usage message.
+
 =item B<-in filename>
 
 This specifies the input filename to read data from or standard input
@@ -48,13 +54,17 @@ if this option is not specified.
 specifies the output filename to write to or standard output by
 default.
 
+=item B<-sigfile file>
+
+Signature file, required for B<verify> operations only
+
 =item B<-inkey file>
 
 the input key file, by default it should be a private key.
 
-=item B<-keyform PEM|DER>
+=item B<-keyform PEM|DER|ENGINE>
 
-the key format PEM, DER or ENGINE.
+the key format PEM, DER or ENGINE. Default is PEM.
 
 =item B<-passin arg>
 
@@ -66,17 +76,9 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 the peer key file, used by key derivation (agreement) operations.
 
-=item B<-peerform PEM|DER>
-
-the peer key format PEM, DER or ENGINE.
-
-=item B<-engine id>
-
-specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
-to attempt to obtain a functional reference to the specified engine,
-thus initialising it if needed. The engine will then be set as the default
-for all available algorithms.
+=item B<-peerform PEM|DER|ENGINE>
 
+the peer key format PEM, DER or ENGINE. Default is PEM.
 
 =item B<-pubin>
 
@@ -117,6 +119,10 @@ decrypt the input data using a private key.
 
 derive a shared secret using the peer key.
 
+=item B<-pkeyopt opt:value>
+
+Public key options specified as opt:value. See NOTES below for more details.
+
 =item B<-hexdump>
 
 hex dump the output data.
@@ -126,6 +132,19 @@ hex dump the output data.
 asn1parse the output data, this is useful when combined with the
 B<-verifyrecover> option when an ASN1 structure is signed.
 
+=item B<-engine id>
+
+specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
+to attempt to obtain a functional reference to the specified engine,
+thus initialising it if needed. The engine will then be set as the default
+for all available algorithms.
+
+=item B<-engine_impl>
+
+When used with the B<-engine> option, it specifies to also use
+engine B<id> for crypto operations.
+
+
 =back
 
 =head1 NOTES
@@ -137,6 +156,19 @@ 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