1PKEYUTL(1) OpenSSL PKEYUTL(1)
2
6 openssl-pkeyutl, pkeyutl - public key algorithm utility
7
9 openssl pkeyutl [-help] [-in file] [-out file] [-sigfile file] [-inkey
10 file] [-keyform PEM|DER|ENGINE] [-passin arg] [-peerkey file]
11 [-peerform PEM|DER|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify]
12 [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-kdf algorithm]
13 [-kdflen length] [-pkeyopt opt:value] [-hexdump] [-asn1parse] [-rand
14 file...] [-writerand file] [-engine id] [-engine_impl]
15
17 The pkeyutl command can be used to perform low-level public key
18 operations using any supported algorithm.
19
21 -help
22 Print out a usage message.
23 -in filename
25 This specifies the input filename to read data from or standard
26 input if this option is not specified.
27 -out filename
29 Specifies the output filename to write to or standard output by
30 default.
31 -sigfile file
33 Signature file, required for verify operations only
34 -inkey file
36 The input key file, by default it should be a private key.
37 -keyform PEM|DER|ENGINE
39 The key format PEM, DER or ENGINE. Default is PEM.
40 -passin arg
42 The input key password source. For more information about the
43 format of arg see "Pass Phrase Options" in openssl(1).
44 -peerkey file
46 The peer key file, used by key derivation (agreement) operations.
47 -peerform PEM|DER|ENGINE
49 The peer key format PEM, DER or ENGINE. Default is PEM.
50 -pubin
52 The input file is a public key.
53 -certin
55 The input is a certificate containing a public key.
56 -rev
58 Reverse the order of the input buffer. This is useful for some
59 libraries (such as CryptoAPI) which represent the buffer in little
60 endian format.
61 -sign
63 Sign the input data (which must be a hash) and output the signed
64 result. This requires a private key.
65 -verify
67 Verify the input data (which must be a hash) against the signature
68 file and indicate if the verification succeeded or failed.
69 -verifyrecover
71 Verify the input data (which must be a hash) and output the
72 recovered data.
73 -encrypt
75 Encrypt the input data using a public key.
76 -decrypt
78 Decrypt the input data using a private key.
79 -derive
81 Derive a shared secret using the peer key.
82 -kdf algorithm
84 Use key derivation function algorithm. The supported algorithms
85 are at present TLS1-PRF and HKDF. Note: additional parameters and
86 the KDF output length will normally have to be set for this to
87 work. See EVP_PKEY_CTX_set_hkdf_md(3) and
88 EVP_PKEY_CTX_set_tls1_prf_md(3) for the supported string parameters
89 of each algorithm.
90 -kdflen length
92 Set the output length for KDF.
93 -pkeyopt opt:value
95 Public key options specified as opt:value. See NOTES below for more
96 details.
97 -hexdump
99 hex dump the output data.
100 -asn1parse
102 Parse the ASN.1 output data, this is useful when combined with the
103 -verifyrecover option when an ASN1 structure is signed.
104 -rand file...
106 A file or files containing random data used to seed the random
107 number generator. Multiple files can be specified separated by an
108 OS-dependent character. The separator is ; for MS-Windows, , for
109 OpenVMS, and : for all others.
110 [-writerand file]
112 Writes random data to the specified file upon exit. This can be
113 used with a subsequent -rand flag.
114 -engine id
116 Specifying an engine (by its unique id string) will cause pkeyutl
117 to attempt to obtain a functional reference to the specified
118 engine, thus initialising it if needed. The engine will then be set
119 as the default for all available algorithms.
120 -engine_impl
122 When used with the -engine option, it specifies to also use engine
123 id for crypto operations.
124
126 The operations and options supported vary according to the key
127 algorithm and its implementation. The OpenSSL operations and options
128 are indicated below.
129 Unless otherwise mentioned all algorithms support the digest:alg option
131 which specifies the digest in use for sign, verify and verifyrecover
132 operations. The value alg should represent a digest name as used in
133 the EVP_get_digestbyname() function for example sha1. This value is not
134 used to hash the input data. It is used (by some algorithms) for
135 sanity-checking the lengths of data passed in to the pkeyutl and for
136 creating the structures that make up the signature (e.g. DigestInfo in
137 RSASSA PKCS#1 v1.5 signatures).
138 This utility does not hash the input data but rather it will use the
140 data directly as input to the signature algorithm. Depending on the key
141 type, signature type, and mode of padding, the maximum acceptable
142 lengths of input data differ. The signed data can't be longer than the
143 key modulus with RSA. In case of ECDSA and DSA the data shouldn't be
144 longer than the field size, otherwise it will be silently truncated to
145 the field size. In any event the input size must not be larger than the
146 largest supported digest size.
147 In other words, if the value of digest is sha1 the input should be the
149 20 bytes long binary encoding of the SHA-1 hash function output.
150 The Ed25519 and Ed448 signature algorithms are not supported by this
152 utility. They accept non-hashed input, but this utility can only be
153 used to sign hashed input.
154
156 The RSA algorithm generally supports the encrypt, decrypt, sign, verify
157 and verifyrecover operations. However, some padding modes support only
158 a subset of these operations. The following additional pkeyopt values
159 are supported:
160 rsa_padding_mode:mode
162 This sets the RSA padding mode. Acceptable values for mode are
163 pkcs1 for PKCS#1 padding, sslv23 for SSLv23 padding, none for no
164 padding, oaep for OAEP mode, x931 for X9.31 mode and pss for PSS.
165 In PKCS#1 padding if the message digest is not set then the
167 supplied data is signed or verified directly instead of using a
168 DigestInfo structure. If a digest is set then the a DigestInfo
169 structure is used and its the length must correspond to the digest
170 type.
171 For oaep mode only encryption and decryption is supported.
173 For x931 if the digest type is set it is used to format the block
175 data otherwise the first byte is used to specify the X9.31 digest
176 ID. Sign, verify and verifyrecover are can be performed in this
177 mode.
178 For pss mode only sign and verify are supported and the digest type
180 must be specified.
181 rsa_pss_saltlen:len
183 For pss mode only this option specifies the salt length. Three
184 special values are supported: "digest" sets the salt length to the
185 digest length, "max" sets the salt length to the maximum
186 permissible value. When verifying "auto" causes the salt length to
187 be automatically determined based on the PSS block structure.
188 rsa_mgf1_md:digest
190 For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest
191 is not explicitly set in PSS mode then the signing digest is used.
192
194 The RSA-PSS algorithm is a restricted version of the RSA algorithm
195 which only supports the sign and verify operations with PSS padding.
196 The following additional pkeyopt values are supported:
197 rsa_padding_mode:mode, rsa_pss_saltlen:len, rsa_mgf1_md:digest
199 These have the same meaning as the RSA algorithm with some
200 additional restrictions. The padding mode can only be set to pss
201 which is the default value.
202 If the key has parameter restrictions than the digest, MGF1 digest
204 and salt length are set to the values specified in the parameters.
205 The digest and MG cannot be changed and the salt length cannot be
206 set to a value less than the minimum restriction.
207
209 The DSA algorithm supports signing and verification operations only.
210 Currently there are no additional -pkeyopt options other than digest.
211 The SHA1 digest is assumed by default.
212
214 The DH algorithm only supports the derivation operation and no
215 additional -pkeyopt options.
216
218 The EC algorithm supports sign, verify and derive operations. The sign
219 and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed
220 by default for the -pkeyopt digest option.
221
223 The X25519 and X448 algorithms support key derivation only. Currently
224 there are no additional options.
225
227 Sign some data using a private key:
228 openssl pkeyutl -sign -in file -inkey key.pem -out sig
230 Recover the signed data (e.g. if an RSA key is used):
232 openssl pkeyutl -verifyrecover -in sig -inkey key.pem
234 Verify the signature (e.g. a DSA key):
236 openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
238 Sign data using a message digest value (this is currently only valid
240 for RSA):
241 openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
243 Derive a shared secret value:
245 openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
247 Hexdump 48 bytes of TLS1 PRF using digest SHA256 and shared secret and
249 seed consisting of the single byte 0xFF:
250 openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
252 -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
253
255 genpkey(1), pkey(1), rsautl(1) dgst(1), rsa(1), genrsa(1),
256 EVP_PKEY_CTX_set_hkdf_md(3), EVP_PKEY_CTX_set_tls1_prf_md(3)
257
259 Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
260 Licensed under the OpenSSL license (the "License"). You may not use
262 this file except in compliance with the License. You can obtain a copy
263 in the file LICENSE in the source distribution or at
264 <https://www.openssl.org/source/license.html>.
2651.1.1l 2021-09-15 PKEYUTL(1)