diff options
| -rw-r--r-- | usr.sbin/openssl/openssl.1 | 214 |
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 |