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