X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Fapps%2Fpkeyutl.pod;h=27be9a90079f6a56b7284fd4e61bcc43a9bcec47;hb=0e0c6821fab18a7d180d3c8dfe18e34fdd2afc54;hp=d18eb8f19713140be61761ea87dc654c080e9cef;hpb=383b8b8ca9ea1074ace1388b58aedf403048da1c;p=oweals%2Fopenssl.git

diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod
index d18eb8f197..27be9a9007 100644
--- a/doc/apps/pkeyutl.pod
+++ b/doc/apps/pkeyutl.pod
@@ -12,6 +12,7 @@ B<openssl> B<pkeyutl>
 [B<-sigfile file>]
 [B<-inkey file>]
 [B<-keyform PEM|DER>]
+[B<-passin arg>]
 [B<-peerkey file>]
 [B<-peerform PEM|DER>]
 [B<-pubin>]
@@ -26,6 +27,7 @@ B<openssl> B<pkeyutl>
 [B<-pkeyopt opt:value>]
 [B<-hexdump>]
 [B<-asn1parse>]
+[B<-engine id>]
 
 =head1 DESCRIPTION
 
@@ -52,7 +54,13 @@ the input key file, by default it should be a private key.
 
 =item B<-keyform PEM|DER>
 
-the key format PEM or DER.
+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)>.
+
 
 =item B<-peerkey file>
 
@@ -60,7 +68,15 @@ the peer key file, used by key derivation (agreement) operations.
 
 =item B<-peerform PEM|DER>
 
-the peer key format PEM or 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<-pubin>
 
@@ -70,6 +86,11 @@ the input file is a public key.
 
 the input is a certificate containing a public key. 
 
+=item B<-rev>
+
+reverse the order of the input buffer. This is useful for some libraries
+(such as CryptoAPI) which represent the buffer in little endian format.
+
 =item B<-sign>
 
 sign the input data and output the signed result. This requires
@@ -112,14 +133,66 @@ B<-verifyrecover> option when an ASN1 structure is signed.
 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: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>.
+
 =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.
 
-[NB: more to be added later]
+=over 4
+
+=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>
+for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
+
+In PKCS#1 padding if the message digest is not set then the supplied data is 
+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<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,
+verify and verifyrecover are can be performed in this mode.
 
+For B<pss> mode only sign and verify are supported and the digest type must be
+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.
+
+=back
+
+=head1 DSA ALGORITHM
+
+The DSA algorithm supports signing and verification operations only. Currently
+there are no additional options other than B<digest>. Only the SHA1
+digest can be used and this digest is assumed by default.
+
+=head1 DH ALGORITHM
+
+The DH algorithm only supports the derivation operation and no additional
+options.
+
+=head1 EC ALGORITHM
+
+The EC algorithm supports sign, verify and derive operations. The sign and
+verify operations use ECDSA and derive uses ECDH. Currently there are no
+additional options other than B<digest>. Only the SHA1 digest can be used and
+this digest is assumed by default.
 
 =head1 EXAMPLES
 
@@ -135,6 +208,14 @@ Verify the signature (e.g. a DSA key):
 
  openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
 
+Sign data using a message digest value (this is currently only valid for RSA):
+
+ openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
+
+Derive a shared secret value:
+
+ openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
+
 =head1 SEE ALSO
 
 L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>