document "openssl pkeyutl";

1 files changed, 212 insertions, 2 deletions

diff --git a/usr.sbin/openssl/openssl.1 b/usr.sbin/openssl/openssl.1
index 73cbf236861..ce075f13008 100644
--- a/usr.sbin/openssl/openssl.1
+++ b/usr.sbin/openssl/openssl.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: openssl.1,v 1.74 2010/10/09 18:22:46 jmc Exp $
+.\" $OpenBSD: openssl.1,v 1.75 2010/10/12 18:36:03 jmc Exp $
 .\" ====================================================================
 .\" Copyright (c) 1998-2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -112,7 +112,7 @@
 .\"
 .\" OPENSSL
 .\"
-.Dd $Mdocdate: October 9 2010 $
+.Dd $Mdocdate: October 12 2010 $
 .Dt OPENSSL 1
 .Os
 .Sh NAME
@@ -318,6 +318,8 @@ PKCS#8 data management.
 PKCS#12 data management.
 .It Cm pkey
 Public and private key management.
+.It Cm pkeyutl
+Public key algorithm cryptographic operation utility.
 .It Cm rand
 Generate pseudo-random bytes.
 .It Cm req
@@ -5144,6 +5146,214 @@ To just output the public part of a private key:
 $ openssl pkey -in key.pem -pubout -out pubkey.pem
 .Ed
 .\"
+.\" PKEYUTL
+.\"
+.Sh PKEYUTL
+.Cm openssl pkeyutl
+.Bk -words
+.Op Fl asn1parse
+.Op Fl certin
+.Op Fl decrypt
+.Op Fl derive
+.Op Fl encrypt
+.Op Fl hexdump
+.Op Fl pubin
+.Op Fl rev
+.Op Fl sign
+.Op Fl verify
+.Op Fl verifyrecover
+.Op Fl engine Ar id
+.Op Fl in Ar file
+.Op Fl inkey Ar file
+.Op Fl keyform Ar DER | PEM
+.Op Fl out Ar file
+.Op Fl passin Ar arg
+.Op Fl peerform Ar DER | PEM
+.Op Fl peerkey Ar file
+.Op Fl pkeyopt Ar opt : Ns Ar value
+.Op Fl sigfile Ar file
+.Ek
+.Pp
+The
+.Nm pkeyutl
+command can be used to perform public key operations using
+any supported algorithm.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl asn1parse
+ASN1parse the output data.
+This is useful when combined with the
+.Fl verifyrecover
+option when an ASN1 structure is signed.
+.It Fl certin
+The input is a certificate containing a public key.
+.It Fl decrypt
+Decrypt the input data using a private key.
+.It Fl derive
+Derive a shared secret using the peer key.
+.It Fl encrypt
+Encrypt the input data using a public key.
+.It Fl engine Ar id
+Specifying an engine (by its unique
+.Ar id
+string) will cause
+.Nm 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.
+.It Fl hexdump
+Hex dump the output data.
+.It Fl in Ar file
+Specify the input filename to read data from,
+or standard input if this option is not specified.
+.It Fl inkey Ar file
+The input key file.
+By default it should be a private key.
+.It Fl keyform Ar DER | PEM
+The key format DER, PEM, or ENGINE.
+.It Fl out Ar file
+Specify the output filename to write to,
+or standard output by default.
+.It Fl passin Ar arg
+The input key password source.
+For more information about the format of
+.Ar arg
+see the
+.Sx PASS PHRASE ARGUMENTS
+section above.
+.It Fl peerform Ar DER | PEM
+The peer key format DER, PEM, or ENGINE.
+.It Fl peerkey Ar file
+The peer key file, used by key derivation (agreement) operations.
+.It Fl pkeyopt Ar opt : Ns Ar value
+Public key options.
+.It Fl pubin
+The input file is a public key.
+.It Fl 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.
+.It Fl sigfile Ar file
+Signature file (verify operation only).
+.It Fl sign
+Sign the input data and output the signed result.
+This requires a private key.
+.It Fl verify
+Verify the input data against the signature file and indicate if the
+verification succeeded or failed.
+.It Fl verifyrecover
+Verify the input data and output the recovered data.
+.El
+.Sh PKEYUTL NOTES
+The operations and options supported vary according to the key algorithm
+and its implementation.
+The
+.Nm OpenSSL
+operations and options are indicated below.
+.Pp
+Unless otherwise mentioned all algorithms support the
+.Ar digest : Ns Ar alg
+option which specifies the digest in use
+for sign, verify, and verifyrecover operations.
+The value
+.Ar alg
+should represent a digest name as used in the
+.Fn EVP_get_digestbyname
+function, for example
+.Cm sha1 .
+.Ss RSA algorithm
+The RSA algorithm supports the
+encrypt, decrypt, sign, verify, and verifyrecover operations in general.
+Some padding modes only support some of these
+operations however.
+.Bl -tag -width Ds
+.It rsa_padding_mode : Ns Ar mode
+This sets the RSA padding mode.
+Acceptable values for
+.Ar mode
+are
+.Cm pkcs1
+for PKCS#1 padding;
+.Cm sslv23
+for SSLv23 padding;
+.Cm none
+for no padding;
+.Cm oaep
+for OAEP mode;
+.Cm x931
+for X9.31 mode;
+and
+.Cm pss
+for PSS.
+.Pp
+In PKCS#1 padding if the message digest is not set then the supplied data is
+signed or verified directly instead of using a DigestInfo structure.
+If a digest is set then a DigestInfo
+structure is used and its length
+must correspond to the digest type.
+.Pp
+For oeap mode only encryption and decryption is supported.
+.Pp
+For 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 can be performed in this mode.
+.Pp
+For pss mode only sign and verify are supported and the digest type must be
+specified.
+.It rsa_pss_saltlen : Ns Ar len
+For 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 PSS block structure.
+.El
+.Ss DSA algorithm
+The DSA algorithm supports the sign and verify operations.
+Currently there are no additional options other than
+.Ar digest .
+Only the SHA1 digest can be used and this digest is assumed by default.
+.Ss DH algorithm
+The DH algorithm supports the derive operation
+and no additional options.
+.Ss EC algorithm
+The EC algorithm supports the sign, verify, and derive operations.
+The sign and verify operations use ECDSA and derive uses ECDH.
+Currently there are no additional options other than
+.Ar digest .
+Only the SHA1 digest can be used and this digest is assumed by default.
+.Sh PKEYUTL EXAMPLES
+Sign some data using a private key:
+.Bd -literal -offset indent
+$ openssl pkeyutl -sign -in file -inkey key.pem -out sig
+.Ed
+.Pp
+Recover the signed data (e.g. if an RSA key is used):
+.Bd -literal -offset indent
+$ openssl pkeyutl -verifyrecover -in sig -inkey key.pem
+.Ed
+.Pp
+Verify the signature (e.g. a DSA key):
+.Bd -literal -offset indent
+$ openssl pkeyutl -verify -in file -sigfile sig \e
+	-inkey key.pem
+.Ed
+.Pp
+Sign data using a message digest value (this is currently only valid for RSA):
+.Bd -literal -offset indent
+$ openssl pkeyutl -sign -in file -inkey key.pem \e
+	-out sig -pkeyopt digest:sha256
+.Ed
+.Pp
+Derive a shared secret value:
+.Bd -literal -offset indent
+$ openssl pkeyutl -derive -inkey key.pem \e
+	-peerkey pubkey.pem -out secret
+.Ed
+.\"
 .\" RAND
 .\"
 .Sh RAND