pkeyutl.pod revision 325337
1=pod 2 3=head1 NAME 4 5openssl-pkeyutl, 6pkeyutl - public key algorithm utility 7 8=head1 SYNOPSIS 9 10B<openssl> B<pkeyutl> 11[B<-in file>] 12[B<-out file>] 13[B<-sigfile file>] 14[B<-inkey file>] 15[B<-keyform PEM|DER>] 16[B<-passin arg>] 17[B<-peerkey file>] 18[B<-peerform PEM|DER>] 19[B<-pubin>] 20[B<-certin>] 21[B<-rev>] 22[B<-sign>] 23[B<-verify>] 24[B<-verifyrecover>] 25[B<-encrypt>] 26[B<-decrypt>] 27[B<-derive>] 28[B<-pkeyopt opt:value>] 29[B<-hexdump>] 30[B<-asn1parse>] 31[B<-engine id>] 32 33=head1 DESCRIPTION 34 35The B<pkeyutl> command can be used to perform public key operations using 36any supported algorithm. 37 38=head1 COMMAND OPTIONS 39 40=over 4 41 42=item B<-in filename> 43 44This specifies the input filename to read data from or standard input 45if this option is not specified. 46 47=item B<-out filename> 48 49specifies the output filename to write to or standard output by 50default. 51 52=item B<-inkey file> 53 54the input key file, by default it should be a private key. 55 56=item B<-keyform PEM|DER> 57 58the key format PEM, DER or ENGINE. 59 60=item B<-passin arg> 61 62the input key password source. For more information about the format of B<arg> 63see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 64 65 66=item B<-peerkey file> 67 68the peer key file, used by key derivation (agreement) operations. 69 70=item B<-peerform PEM|DER> 71 72the peer key format PEM, DER or ENGINE. 73 74=item B<-engine id> 75 76specifying an engine (by its unique B<id> string) will cause B<pkeyutl> 77to attempt to obtain a functional reference to the specified engine, 78thus initialising it if needed. The engine will then be set as the default 79for all available algorithms. 80 81 82=item B<-pubin> 83 84the input file is a public key. 85 86=item B<-certin> 87 88the input is a certificate containing a public key. 89 90=item B<-rev> 91 92reverse the order of the input buffer. This is useful for some libraries 93(such as CryptoAPI) which represent the buffer in little endian format. 94 95=item B<-sign> 96 97sign the input data and output the signed result. This requires 98a private key. 99 100=item B<-verify> 101 102verify the input data against the signature file and indicate if the 103verification succeeded or failed. 104 105=item B<-verifyrecover> 106 107verify the input data and output the recovered data. 108 109=item B<-encrypt> 110 111encrypt the input data using a public key. 112 113=item B<-decrypt> 114 115decrypt the input data using a private key. 116 117=item B<-derive> 118 119derive a shared secret using the peer key. 120 121=item B<-hexdump> 122 123hex dump the output data. 124 125=item B<-asn1parse> 126 127asn1parse the output data, this is useful when combined with the 128B<-verifyrecover> option when an ASN1 structure is signed. 129 130=back 131 132=head1 NOTES 133 134The operations and options supported vary according to the key algorithm 135and its implementation. The OpenSSL operations and options are indicated below. 136 137Unless otherwise mentioned all algorithms support the B<digest:alg> option 138which specifies the digest in use for sign, verify and verifyrecover operations. 139The value B<alg> should represent a digest name as used in the 140EVP_get_digestbyname() function for example B<sha1>. 141This value is used only for sanity-checking the lengths of data passed in to 142the B<pkeyutl> and for creating the structures that make up the signature 143(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures). 144In case of RSA, ECDSA and DSA signatures, this utility 145will not perform hashing on input data but rather use the data directly as 146input of signature algorithm. Depending on key type, signature type and mode 147of padding, the maximum acceptable lengths of input data differ. In general, 148with RSA the signed data can't be longer than the key modulus, in case of ECDSA 149and DSA the data shouldn't be longer than field size, otherwise it will be 150silently truncated to field size. 151 152In other words, if the value of digest is B<sha1> the input should be 20 bytes 153long binary encoding of SHA-1 hash function output. 154 155=head1 RSA ALGORITHM 156 157The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover 158operations in general. Some padding modes only support some of these 159operations however. 160 161=over 4 162 163=item -B<rsa_padding_mode:mode> 164 165This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for 166PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> 167for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS. 168 169In PKCS#1 padding if the message digest is not set then the supplied data is 170signed or verified directly instead of using a B<DigestInfo> structure. If a 171digest is set then the a B<DigestInfo> structure is used and its the length 172must correspond to the digest type. 173 174For B<oeap> mode only encryption and decryption is supported. 175 176For B<x931> if the digest type is set it is used to format the block data 177otherwise the first byte is used to specify the X9.31 digest ID. Sign, 178verify and verifyrecover are can be performed in this mode. 179 180For B<pss> mode only sign and verify are supported and the digest type must be 181specified. 182 183=item B<rsa_pss_saltlen:len> 184 185For B<pss> mode only this option specifies the salt length. Two special values 186are supported: -1 sets the salt length to the digest length. When signing -2 187sets the salt length to the maximum permissible value. When verifying -2 causes 188the salt length to be automatically determined based on the B<PSS> block 189structure. 190 191=back 192 193=head1 DSA ALGORITHM 194 195The DSA algorithm supports signing and verification operations only. Currently 196there are no additional options other than B<digest>. Only the SHA1 197digest can be used and this digest is assumed by default. 198 199=head1 DH ALGORITHM 200 201The DH algorithm only supports the derivation operation and no additional 202options. 203 204=head1 EC ALGORITHM 205 206The EC algorithm supports sign, verify and derive operations. The sign and 207verify operations use ECDSA and derive uses ECDH. Currently there are no 208additional options other than B<digest>. Only the SHA1 digest can be used and 209this digest is assumed by default. 210 211=head1 EXAMPLES 212 213Sign some data using a private key: 214 215 openssl pkeyutl -sign -in file -inkey key.pem -out sig 216 217Recover the signed data (e.g. if an RSA key is used): 218 219 openssl pkeyutl -verifyrecover -in sig -inkey key.pem 220 221Verify the signature (e.g. a DSA key): 222 223 openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem 224 225Sign data using a message digest value (this is currently only valid for RSA): 226 227 openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 228 229Derive a shared secret value: 230 231 openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret 232 233=head1 SEE ALSO 234 235L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)> 236L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> 237