1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5325337Sjkimopenssl-pkeyutl, 6238384Sjkimpkeyutl - public key algorithm utility 7238384Sjkim 8238384Sjkim=head1 SYNOPSIS 9238384Sjkim 10238384SjkimB<openssl> B<pkeyutl> 11238384Sjkim[B<-in file>] 12238384Sjkim[B<-out file>] 13238384Sjkim[B<-sigfile file>] 14238384Sjkim[B<-inkey file>] 15238384Sjkim[B<-keyform PEM|DER>] 16238384Sjkim[B<-passin arg>] 17238384Sjkim[B<-peerkey file>] 18238384Sjkim[B<-peerform PEM|DER>] 19238384Sjkim[B<-pubin>] 20238384Sjkim[B<-certin>] 21238384Sjkim[B<-rev>] 22238384Sjkim[B<-sign>] 23238384Sjkim[B<-verify>] 24238384Sjkim[B<-verifyrecover>] 25238384Sjkim[B<-encrypt>] 26238384Sjkim[B<-decrypt>] 27238384Sjkim[B<-derive>] 28238384Sjkim[B<-pkeyopt opt:value>] 29238384Sjkim[B<-hexdump>] 30238384Sjkim[B<-asn1parse>] 31238384Sjkim[B<-engine id>] 32238384Sjkim 33238384Sjkim=head1 DESCRIPTION 34238384Sjkim 35238384SjkimThe B<pkeyutl> command can be used to perform public key operations using 36238384Sjkimany supported algorithm. 37238384Sjkim 38238384Sjkim=head1 COMMAND OPTIONS 39238384Sjkim 40238384Sjkim=over 4 41238384Sjkim 42238384Sjkim=item B<-in filename> 43238384Sjkim 44238384SjkimThis specifies the input filename to read data from or standard input 45238384Sjkimif this option is not specified. 46238384Sjkim 47238384Sjkim=item B<-out filename> 48238384Sjkim 49238384Sjkimspecifies the output filename to write to or standard output by 50238384Sjkimdefault. 51238384Sjkim 52238384Sjkim=item B<-inkey file> 53238384Sjkim 54238384Sjkimthe input key file, by default it should be a private key. 55238384Sjkim 56238384Sjkim=item B<-keyform PEM|DER> 57238384Sjkim 58238384Sjkimthe key format PEM, DER or ENGINE. 59238384Sjkim 60238384Sjkim=item B<-passin arg> 61238384Sjkim 62238384Sjkimthe input key password source. For more information about the format of B<arg> 63238384Sjkimsee the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 64238384Sjkim 65238384Sjkim 66238384Sjkim=item B<-peerkey file> 67238384Sjkim 68238384Sjkimthe peer key file, used by key derivation (agreement) operations. 69238384Sjkim 70238384Sjkim=item B<-peerform PEM|DER> 71238384Sjkim 72238384Sjkimthe peer key format PEM, DER or ENGINE. 73238384Sjkim 74238384Sjkim=item B<-engine id> 75238384Sjkim 76238384Sjkimspecifying an engine (by its unique B<id> string) will cause B<pkeyutl> 77238384Sjkimto attempt to obtain a functional reference to the specified engine, 78238384Sjkimthus initialising it if needed. The engine will then be set as the default 79238384Sjkimfor all available algorithms. 80238384Sjkim 81238384Sjkim 82238384Sjkim=item B<-pubin> 83238384Sjkim 84238384Sjkimthe input file is a public key. 85238384Sjkim 86238384Sjkim=item B<-certin> 87238384Sjkim 88238384Sjkimthe input is a certificate containing a public key. 89238384Sjkim 90238384Sjkim=item B<-rev> 91238384Sjkim 92238384Sjkimreverse the order of the input buffer. This is useful for some libraries 93238384Sjkim(such as CryptoAPI) which represent the buffer in little endian format. 94238384Sjkim 95238384Sjkim=item B<-sign> 96238384Sjkim 97238384Sjkimsign the input data and output the signed result. This requires 98238384Sjkima private key. 99238384Sjkim 100238384Sjkim=item B<-verify> 101238384Sjkim 102238384Sjkimverify the input data against the signature file and indicate if the 103238384Sjkimverification succeeded or failed. 104238384Sjkim 105238384Sjkim=item B<-verifyrecover> 106238384Sjkim 107238384Sjkimverify the input data and output the recovered data. 108238384Sjkim 109238384Sjkim=item B<-encrypt> 110238384Sjkim 111238384Sjkimencrypt the input data using a public key. 112238384Sjkim 113238384Sjkim=item B<-decrypt> 114238384Sjkim 115238384Sjkimdecrypt the input data using a private key. 116238384Sjkim 117238384Sjkim=item B<-derive> 118238384Sjkim 119238384Sjkimderive a shared secret using the peer key. 120238384Sjkim 121238384Sjkim=item B<-hexdump> 122238384Sjkim 123238384Sjkimhex dump the output data. 124238384Sjkim 125238384Sjkim=item B<-asn1parse> 126238384Sjkim 127238384Sjkimasn1parse the output data, this is useful when combined with the 128238384SjkimB<-verifyrecover> option when an ASN1 structure is signed. 129238384Sjkim 130238384Sjkim=back 131238384Sjkim 132238384Sjkim=head1 NOTES 133238384Sjkim 134238384SjkimThe operations and options supported vary according to the key algorithm 135238384Sjkimand its implementation. The OpenSSL operations and options are indicated below. 136238384Sjkim 137238384SjkimUnless otherwise mentioned all algorithms support the B<digest:alg> option 138238384Sjkimwhich specifies the digest in use for sign, verify and verifyrecover operations. 139238384SjkimThe value B<alg> should represent a digest name as used in the 140238384SjkimEVP_get_digestbyname() function for example B<sha1>. 141296279SjkimThis value is used only for sanity-checking the lengths of data passed in to 142296279Sjkimthe B<pkeyutl> and for creating the structures that make up the signature 143296279Sjkim(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures). 144296279SjkimIn case of RSA, ECDSA and DSA signatures, this utility 145296279Sjkimwill not perform hashing on input data but rather use the data directly as 146296279Sjkiminput of signature algorithm. Depending on key type, signature type and mode 147296279Sjkimof padding, the maximum acceptable lengths of input data differ. In general, 148296279Sjkimwith RSA the signed data can't be longer than the key modulus, in case of ECDSA 149296279Sjkimand DSA the data shouldn't be longer than field size, otherwise it will be 150296279Sjkimsilently truncated to field size. 151238384Sjkim 152296279SjkimIn other words, if the value of digest is B<sha1> the input should be 20 bytes 153296279Sjkimlong binary encoding of SHA-1 hash function output. 154296279Sjkim 155238384Sjkim=head1 RSA ALGORITHM 156238384Sjkim 157238384SjkimThe RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover 158238384Sjkimoperations in general. Some padding modes only support some of these 159238384Sjkimoperations however. 160238384Sjkim 161238384Sjkim=over 4 162238384Sjkim 163238384Sjkim=item -B<rsa_padding_mode:mode> 164238384Sjkim 165238384SjkimThis sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for 166238384SjkimPKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> 167238384Sjkimfor B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS. 168238384Sjkim 169238384SjkimIn PKCS#1 padding if the message digest is not set then the supplied data is 170238384Sjkimsigned or verified directly instead of using a B<DigestInfo> structure. If a 171238384Sjkimdigest is set then the a B<DigestInfo> structure is used and its the length 172238384Sjkimmust correspond to the digest type. 173238384Sjkim 174238384SjkimFor B<oeap> mode only encryption and decryption is supported. 175238384Sjkim 176238384SjkimFor B<x931> if the digest type is set it is used to format the block data 177238384Sjkimotherwise the first byte is used to specify the X9.31 digest ID. Sign, 178238384Sjkimverify and verifyrecover are can be performed in this mode. 179238384Sjkim 180238384SjkimFor B<pss> mode only sign and verify are supported and the digest type must be 181238384Sjkimspecified. 182238384Sjkim 183238384Sjkim=item B<rsa_pss_saltlen:len> 184238384Sjkim 185238384SjkimFor B<pss> mode only this option specifies the salt length. Two special values 186238384Sjkimare supported: -1 sets the salt length to the digest length. When signing -2 187238384Sjkimsets the salt length to the maximum permissible value. When verifying -2 causes 188238384Sjkimthe salt length to be automatically determined based on the B<PSS> block 189238384Sjkimstructure. 190238384Sjkim 191238384Sjkim=back 192238384Sjkim 193238384Sjkim=head1 DSA ALGORITHM 194238384Sjkim 195238384SjkimThe DSA algorithm supports signing and verification operations only. Currently 196238384Sjkimthere are no additional options other than B<digest>. Only the SHA1 197238384Sjkimdigest can be used and this digest is assumed by default. 198238384Sjkim 199238384Sjkim=head1 DH ALGORITHM 200238384Sjkim 201238384SjkimThe DH algorithm only supports the derivation operation and no additional 202238384Sjkimoptions. 203238384Sjkim 204238384Sjkim=head1 EC ALGORITHM 205238384Sjkim 206238384SjkimThe EC algorithm supports sign, verify and derive operations. The sign and 207238384Sjkimverify operations use ECDSA and derive uses ECDH. Currently there are no 208238384Sjkimadditional options other than B<digest>. Only the SHA1 digest can be used and 209238384Sjkimthis digest is assumed by default. 210238384Sjkim 211238384Sjkim=head1 EXAMPLES 212238384Sjkim 213238384SjkimSign some data using a private key: 214238384Sjkim 215238384Sjkim openssl pkeyutl -sign -in file -inkey key.pem -out sig 216238384Sjkim 217238384SjkimRecover the signed data (e.g. if an RSA key is used): 218238384Sjkim 219238384Sjkim openssl pkeyutl -verifyrecover -in sig -inkey key.pem 220238384Sjkim 221238384SjkimVerify the signature (e.g. a DSA key): 222238384Sjkim 223238384Sjkim openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem 224238384Sjkim 225238384SjkimSign data using a message digest value (this is currently only valid for RSA): 226238384Sjkim 227238384Sjkim openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 228238384Sjkim 229238384SjkimDerive a shared secret value: 230238384Sjkim 231238384Sjkim openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret 232238384Sjkim 233238384Sjkim=head1 SEE ALSO 234238384Sjkim 235238384SjkimL<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)> 236238384SjkimL<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> 237