From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/apps/pkeyutl.pod | 293 ++++++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 openssl-1.1.0h/doc/apps/pkeyutl.pod (limited to 'openssl-1.1.0h/doc/apps/pkeyutl.pod') diff --git a/openssl-1.1.0h/doc/apps/pkeyutl.pod b/openssl-1.1.0h/doc/apps/pkeyutl.pod new file mode 100644 index 0000000..e72486d --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkeyutl.pod @@ -0,0 +1,293 @@ +=pod + +=head1 NAME + +openssl-pkeyutl, +pkeyutl - public key algorithm utility + +=head1 SYNOPSIS + +B B +[B<-help>] +[B<-in file>] +[B<-out file>] +[B<-sigfile file>] +[B<-inkey file>] +[B<-keyform PEM|DER|ENGINE>] +[B<-passin arg>] +[B<-peerkey file>] +[B<-peerform PEM|DER|ENGINE>] +[B<-pubin>] +[B<-certin>] +[B<-rev>] +[B<-sign>] +[B<-verify>] +[B<-verifyrecover>] +[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 command can be used to perform public key operations using +any supported algorithm. + +=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 +if this option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-sigfile file> + +Signature file, required for B operations only + +=item B<-inkey file> + +the input key file, by default it should be a private key. + +=item B<-keyform PEM|DER|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 +see the B section in L. + + +=item B<-peerkey file> + +the peer key file, used by key derivation (agreement) operations. + +=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. + +=item B<-certin> + +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 +a private key. + +=item B<-verify> + +verify the input data against the signature file and indicate if the +verification succeeded or failed. + +=item B<-verifyrecover> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using a public key. + +=item B<-decrypt> + +decrypt the input data using a private key. + +=item B<-derive> + +derive a shared secret using the peer key. + +=item B<-kdf algorithm> + +Use key derivation function B. The supported algorithms are +at present B and B. +Note: additional parameters and the KDF output length will normally have to be +set for this to work. +See L and L +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. + +=item B<-asn1parse> + +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 string) will cause B +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 for crypto operations. + +=back + +=head1 NOTES + +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 option +which specifies the digest in use for sign, verify and verifyrecover operations. +The value B should represent a digest name as used in the +EVP_get_digestbyname() function for example B. +This value is used only for sanity-checking the lengths of data passed in to +the B and for creating the structures that make up the signature +(e.g. B 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 the input should be 20 bytes +long binary encoding of SHA-1 hash function output. + +=head1 RSA ALGORITHM + +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 values are supported: + +=over 4 + +=item B + +This sets the RSA padding mode. Acceptable values for B are B for +PKCS#1 padding, B for SSLv23 padding, B for no padding, B +for B mode, B for X9.31 mode and B 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 structure. If a +digest is set then the a B structure is used and its the length +must correspond to the digest type. + +For B mode only encryption and decryption is supported. + +For B 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 mode only sign and verify are supported and the digest type must be +specified. + +=item B + +For B 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 block +structure. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional options other than B. 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. 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: + + openssl pkeyutl -sign -in file -inkey key.pem -out sig + +Recover the signed data (e.g. if an RSA key is used): + + openssl pkeyutl -verifyrecover -in sig -inkey key.pem + +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 + +Hexdump 48 bytes of TLS1 PRF using digest B 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, L, L +L, L, L, +L, L + +=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. + +=cut -- cgit v1.2.3