diff options
Diffstat (limited to 'deps/openssl/openssl/doc/apps/pkeyutl.pod')
| -rw-r--r-- | deps/openssl/openssl/doc/apps/pkeyutl.pod | 109 |
1 files changed, 83 insertions, 26 deletions
diff --git a/deps/openssl/openssl/doc/apps/pkeyutl.pod b/deps/openssl/openssl/doc/apps/pkeyutl.pod index 78b3b02a7d..e72486defc 100644 --- a/deps/openssl/openssl/doc/apps/pkeyutl.pod +++ b/deps/openssl/openssl/doc/apps/pkeyutl.pod @@ -8,14 +8,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>] @@ -25,20 +26,27 @@ B<openssl> B<pkeyutl> [B<-encrypt>] [B<-decrypt>] [B<-derive>] +[B<-kdf algorithm>] +[B<-kdflen length>] [B<-pkeyopt opt:value>] [B<-hexdump>] [B<-asn1parse>] [B<-engine id>] +[B<-engine_impl>] =head1 DESCRIPTION The B<pkeyutl> command can be used to perform public key operations using any supported algorithm. -=head1 COMMAND OPTIONS +=head1 OPTIONS =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 @@ -49,43 +57,39 @@ 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> 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)>. +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. =item B<-peerkey file> 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> -the input file is a public key. +the input file is a public key. =item B<-certin> -the input is a certificate containing a public key. +the input is a certificate containing a public key. =item B<-rev> @@ -118,6 +122,23 @@ decrypt the input data using a private key. derive a shared secret using the peer key. +=item B<-kdf algorithm> + +Use key derivation function B<algorithm>. The supported algorithms are +at present B<TLS1-PRF> and B<HKDF>. +Note: additional parameters and the KDF output length will normally have to be +set for this to work. +See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)> +for the supported string parameters of each algorithm. + +=item B<-kdflen length> + +Set the output length for KDF. + +=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. @@ -127,6 +148,18 @@ 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 @@ -154,24 +187,25 @@ 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> 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 +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<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, @@ -208,6 +242,11 @@ 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 X25519 ALGORITHM + +The X25519 algorithm supports key derivation only. Currently there are no +additional options. + =head1 EXAMPLES Sign some data using a private key: @@ -230,7 +269,25 @@ Derive a shared secret value: openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret +Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and +seed consisting of the single byte 0xFF: + + openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \ + -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump + =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)>, +L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |