Add ec -check option

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

diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod
index 9366d967cbad4a1079a33169a70806a4bf1ed3c0..d44f73aeecc71ddeffa432ce08bd4b1fb2829e77 100644 (file)
--- a/doc/apps/pkeyutl.pod
+++ b/doc/apps/pkeyutl.pod
@@ -11,9 +11,10 @@ B<openssl> B<pkeyutl>
 [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>]
@@ -26,6 +27,7 @@ B<openssl> B<pkeyutl>
 [B<-pkeyopt opt:value>]
 [B<-hexdump>]
 [B<-asn1parse>]
+[B<-engine id>]
 
 =head1 DESCRIPTION
 
@@ -50,17 +52,31 @@ default.
 
 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.
+
+=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)>.
 
-the key format PEM or DER.
 
 =item B<-peerkey file>
 
 the peer key file, used by key derivation (agreement) operations.
 
-=item B<-peerform PEM|DER>
+=item B<-peerform PEM|DER|ENGINE>
+
+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.
 
-the peer key format PEM or DER.
 
 =item B<-pubin>
 
@@ -121,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>
@@ -141,7 +171,7 @@ signed or verified directly instead of using a B<DigestInfo> structure. If a
 digest is set then the a B<DigestInfo> structure is used and its the length
 must correspond to the digest type.
 
-For B<oeap> mode only encryption and decryption is supported.
+For B<oaep> mode only encryption and decryption is supported.
 
 For B<x931> if the digest type is set it is used to format the block data
 otherwise the first byte is used to specify the X9.31 digest ID. Sign,
@@ -152,11 +182,11 @@ specified.
 
 =item B<rsa_pss_saltlen:len>
 
-For B<pss> mode only this option specifies the salt length. Two special
-values are supported: -1 sets the salt length to the digest length. When
-signing -2 sets the salt length to the maximum permissible value. When
-verifying -2 causes the salt length to be automatically determined based
-on the B<PSS> block structure.
+For B<pss> mode only this option specifies the salt length. Two special values
+are supported: -1 sets the salt length to the digest length. When signing -2
+sets the salt length to the maximum permissible value. When verifying -2 causes
+the salt length to be automatically determined based on the B<PSS> block
+structure.
 
 =back
 
@@ -202,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)>