]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | openssl - OpenSSL command line tool | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> | |
10 | I<command> | |
d86925e6 RS |
11 | [ I<options> ... ] |
12 | [ I<parameters> ... ] | |
aba3e65f | 13 | |
b2bdfb63 RL |
14 | B<openssl> |
15 | B<list> | |
16 | B<-standard-commands> | | |
17 | B<-digest-commands> | | |
18 | B<-cipher-commands> | | |
19 | B<-cipher-algorithms> | | |
20 | B<-digest-algorithms> | | |
21 | B<-mac-algorithms> | | |
22 | B<-public-key-algorithms> | |
88220dcb | 23 | |
d86925e6 | 24 | B<openssl> B<no->I<XXX> [ I<options> ] |
88220dcb | 25 | |
aba3e65f DSH |
26 | =head1 DESCRIPTION |
27 | ||
28 | OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL | |
29 | v2/v3) and Transport Layer Security (TLS v1) network protocols and related | |
30 | cryptography standards required by them. | |
31 | ||
32 | The B<openssl> program is a command line tool for using the various | |
4c583c36 AM |
33 | cryptography functions of OpenSSL's B<crypto> library from the shell. |
34 | It can be used for | |
aba3e65f | 35 | |
e4549295 DSH |
36 | o Creation and management of private keys, public keys and parameters |
37 | o Public key cryptographic operations | |
4c583c36 | 38 | o Creation of X.509 certificates, CSRs and CRLs |
4d768e96 | 39 | o Calculation of Message Digests and Message Authentication Codes |
aba3e65f DSH |
40 | o Encryption and Decryption with Ciphers |
41 | o SSL/TLS Client and Server Tests | |
54a34aec | 42 | o Handling of S/MIME signed or encrypted mail |
9c0586d5 | 43 | o Timestamp requests, generation and verification |
aba3e65f DSH |
44 | |
45 | =head1 COMMAND SUMMARY | |
46 | ||
22bb8c25 | 47 | The B<openssl> program provides a rich variety of commands (I<command> in |
d86925e6 RS |
48 | the L</SYNOPSIS> above). |
49 | Each command can have many options and argument parameters, shown above as | |
50 | I<options> and I<parameters>. | |
aba3e65f | 51 | |
1362190b | 52 | Detailed documentation and use cases for most standard subcommands are available |
1903a9b7 | 53 | (e.g., L<openssl-x509(1)>). |
1362190b | 54 | |
e9681f83 RS |
55 | Many commands use an external configuration file for some or all of their |
56 | arguments and have a B<-config> option to specify that file. | |
22bb8c25 RS |
57 | The default name of the file is F<openssl.cnf> in the default certificate |
58 | storage area, which can be determined from the L<openssl-version(1)> | |
59 | command. | |
e9681f83 | 60 | The environment variable B<OPENSSL_CONF> can be used to specify |
22bb8c25 RS |
61 | a different location of the file. |
62 | See L<openssl-env(7)>. | |
e9681f83 | 63 | |
2f0ea936 RL |
64 | The list options B<-standard-commands>, B<-digest-commands>, |
65 | and B<-cipher-commands> output a list (one entry per line) of the names | |
88220dcb | 66 | of all standard commands, message digest commands, or cipher commands, |
35a810bb | 67 | respectively, that are available. |
88220dcb | 68 | |
2f0ea936 RL |
69 | The list parameters B<-cipher-algorithms>, B<-digest-algorithms>, |
70 | and B<-mac-algorithms> list all cipher, message digest, and message | |
4d768e96 | 71 | authentication code names, one entry per line. Aliases are listed as: |
112161bd DSH |
72 | |
73 | from => to | |
74 | ||
2f0ea936 | 75 | The list parameter B<-public-key-algorithms> lists all supported public |
112161bd DSH |
76 | key algorithms. |
77 | ||
c03726ca | 78 | The command B<no->I<XXX> tests whether a command of the |
88220dcb BM |
79 | specified name is available. If no command named I<XXX> exists, it |
80 | returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 | |
81 | and prints I<XXX>. In both cases, the output goes to B<stdout> and | |
82 | nothing is printed to B<stderr>. Additional command line arguments | |
83 | are always ignored. Since for each cipher there is a command of the | |
84 | same name, this provides an easy way for shell scripts to test for the | |
85 | availability of ciphers in the B<openssl> program. (B<no->I<XXX> is | |
86 | not able to detect pseudo-commands such as B<quit>, | |
c03726ca | 87 | B<list>, or B<no->I<XXX> itself.) |
88220dcb | 88 | |
22bb8c25 | 89 | =head2 Standard Commands |
aba3e65f | 90 | |
e1271ac2 | 91 | =over 4 |
aba3e65f | 92 | |
dfee8626 | 93 | =item B<asn1parse> |
aba3e65f DSH |
94 | |
95 | Parse an ASN.1 sequence. | |
96 | ||
dfee8626 | 97 | =item B<ca> |
aba3e65f | 98 | |
4c583c36 | 99 | Certificate Authority (CA) Management. |
aba3e65f | 100 | |
dfee8626 | 101 | =item B<ciphers> |
aba3e65f DSH |
102 | |
103 | Cipher Suite Description Determination. | |
104 | ||
dfee8626 | 105 | =item B<cms> |
e5fa864f | 106 | |
c4de074e | 107 | CMS (Cryptographic Message Syntax) utility. |
e5fa864f | 108 | |
dfee8626 | 109 | =item B<crl> |
aba3e65f DSH |
110 | |
111 | Certificate Revocation List (CRL) Management. | |
112 | ||
dfee8626 | 113 | =item B<crl2pkcs7> |
aba3e65f DSH |
114 | |
115 | CRL to PKCS#7 Conversion. | |
116 | ||
dfee8626 | 117 | =item B<dgst> |
aba3e65f | 118 | |
4d768e96 | 119 | Message Digest calculation. MAC calculations are superseded by |
8bc93d2f | 120 | L<openssl-mac(1)>. |
aba3e65f | 121 | |
727daea7 | 122 | =item B<dh> |
aba3e65f | 123 | |
727daea7 | 124 | Diffie-Hellman Parameter Management. |
8bc93d2f | 125 | Obsoleted by L<openssl-dhparam(1)>. |
aba3e65f | 126 | |
dfee8626 | 127 | =item B<dhparam> |
e5fa864f | 128 | |
4c583c36 | 129 | Generation and Management of Diffie-Hellman Parameters. Superseded by |
8bc93d2f | 130 | L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>. |
e5fa864f | 131 | |
dfee8626 | 132 | =item B<dsa> |
aba3e65f DSH |
133 | |
134 | DSA Data Management. | |
135 | ||
dfee8626 | 136 | =item B<dsaparam> |
aba3e65f | 137 | |
4c583c36 | 138 | DSA Parameter Generation and Management. Superseded by |
8bc93d2f | 139 | L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>. |
aba3e65f | 140 | |
dfee8626 | 141 | =item B<ec> |
e5fa864f | 142 | |
c4de074e | 143 | EC (Elliptic curve) key processing. |
e5fa864f | 144 | |
dfee8626 | 145 | =item B<ecparam> |
e5fa864f | 146 | |
c4de074e | 147 | EC parameter manipulation and generation. |
e5fa864f | 148 | |
dfee8626 | 149 | =item B<enc> |
aba3e65f | 150 | |
22bb8c25 | 151 | Encryption, decryption, and encoding. |
aba3e65f | 152 | |
dfee8626 | 153 | =item B<engine> |
aba3e65f | 154 | |
4c583c36 | 155 | Engine (loadable module) information and manipulation. |
aba3e65f | 156 | |
dfee8626 | 157 | =item B<errstr> |
727daea7 | 158 | |
e5fa864f | 159 | Error Number to Error String Conversion. |
727daea7 BM |
160 | |
161 | =item B<gendh> | |
aba3e65f DSH |
162 | |
163 | Generation of Diffie-Hellman Parameters. | |
8bc93d2f | 164 | Obsoleted by L<openssl-dhparam(1)>. |
aba3e65f | 165 | |
dfee8626 | 166 | =item B<gendsa> |
aba3e65f | 167 | |
4c583c36 | 168 | Generation of DSA Private Key from Parameters. Superseded by |
8bc93d2f | 169 | L<openssl-genpkey(1)> and L<openssl-pkey(1)>. |
e4549295 | 170 | |
dfee8626 | 171 | =item B<genpkey> |
e4549295 DSH |
172 | |
173 | Generation of Private Key or Parameters. | |
aba3e65f | 174 | |
dfee8626 | 175 | =item B<genrsa> |
aba3e65f | 176 | |
8bc93d2f | 177 | Generation of RSA Private Key. Superseded by L<openssl-genpkey(1)>. |
aba3e65f | 178 | |
0109e030 RL |
179 | =item B<info> |
180 | ||
181 | Display diverse information built into the OpenSSL libraries. | |
182 | ||
c54492ec SL |
183 | =item B<kdf> |
184 | ||
185 | Key Derivation Functions. | |
186 | ||
4d768e96 SL |
187 | =item B<mac> |
188 | ||
189 | Message Authentication Code Calculation. | |
190 | ||
dfee8626 | 191 | =item B<nseq> |
e5fa864f | 192 | |
c4de074e | 193 | Create or examine a Netscape certificate sequence. |
e5fa864f | 194 | |
dfee8626 | 195 | =item B<ocsp> |
a068630a UM |
196 | |
197 | Online Certificate Status Protocol utility. | |
198 | ||
dfee8626 | 199 | =item B<passwd> |
5160448b RL |
200 | |
201 | Generation of hashed passwords. | |
202 | ||
dfee8626 | 203 | =item B<pkcs12> |
3f1c4e49 BM |
204 | |
205 | PKCS#12 Data Management. | |
206 | ||
dfee8626 | 207 | =item B<pkcs7> |
aba3e65f DSH |
208 | |
209 | PKCS#7 Data Management. | |
210 | ||
dfee8626 | 211 | =item B<pkcs8> |
f0b843c1 RL |
212 | |
213 | PKCS#8 format private key conversion tool. | |
214 | ||
dfee8626 | 215 | =item B<pkey> |
e4549295 DSH |
216 | |
217 | Public and private key management. | |
218 | ||
dfee8626 | 219 | =item B<pkeyparam> |
e4549295 DSH |
220 | |
221 | Public key algorithm parameter management. | |
222 | ||
dfee8626 | 223 | =item B<pkeyutl> |
e5fa864f DSH |
224 | |
225 | Public key algorithm cryptographic operation utility. | |
226 | ||
dfee8626 | 227 | =item B<prime> |
f0b843c1 RL |
228 | |
229 | Compute prime numbers. | |
230 | ||
dfee8626 | 231 | =item B<rand> |
afbd0746 BM |
232 | |
233 | Generate pseudo-random bytes. | |
234 | ||
dfee8626 | 235 | =item B<rehash> |
f0b843c1 | 236 | |
24c34608 | 237 | Create symbolic links to certificate and CRL files named by the hash values. |
f0b843c1 | 238 | |
dfee8626 | 239 | =item B<req> |
aba3e65f | 240 | |
e4549295 | 241 | PKCS#10 X.509 Certificate Signing Request (CSR) Management. |
aba3e65f | 242 | |
dfee8626 | 243 | =item B<rsa> |
aba3e65f | 244 | |
e4549295 | 245 | RSA key management. |
aba3e65f | 246 | |
dfee8626 | 247 | =item B<rsautl> |
34417732 | 248 | |
e4549295 | 249 | RSA utility for signing, verification, encryption, and decryption. Superseded |
8bc93d2f | 250 | by L<openssl-pkeyutl(1)>. |
34417732 | 251 | |
dfee8626 | 252 | =item B<s_client> |
aba3e65f DSH |
253 | |
254 | This implements a generic SSL/TLS client which can establish a transparent | |
255 | connection to a remote server speaking SSL/TLS. It's intended for testing | |
256 | purposes only and provides only rudimentary interface functionality but | |
257 | internally uses mostly all functionality of the OpenSSL B<ssl> library. | |
258 | ||
dfee8626 | 259 | =item B<s_server> |
aba3e65f DSH |
260 | |
261 | This implements a generic SSL/TLS server which accepts connections from remote | |
262 | clients speaking SSL/TLS. It's intended for testing purposes only and provides | |
263 | only rudimentary interface functionality but internally uses mostly all | |
264 | functionality of the OpenSSL B<ssl> library. It provides both an own command | |
265 | line oriented protocol for testing SSL functions and a simple HTTP response | |
266 | facility to emulate an SSL/TLS-aware webserver. | |
267 | ||
dfee8626 | 268 | =item B<s_time> |
aba3e65f DSH |
269 | |
270 | SSL Connection Timer. | |
271 | ||
dfee8626 | 272 | =item B<sess_id> |
aba3e65f DSH |
273 | |
274 | SSL Session Data Management. | |
275 | ||
dfee8626 | 276 | =item B<smime> |
54a34aec DSH |
277 | |
278 | S/MIME mail processing. | |
279 | ||
dfee8626 | 280 | =item B<speed> |
aba3e65f DSH |
281 | |
282 | Algorithm Speed Measurement. | |
283 | ||
dfee8626 | 284 | =item B<spkac> |
e5fa864f | 285 | |
c4de074e | 286 | SPKAC printing and generating utility. |
e5fa864f | 287 | |
dfee8626 | 288 | =item B<srp> |
f0b843c1 RL |
289 | |
290 | Maintain SRP password file. | |
291 | ||
dfee8626 | 292 | =item B<storeutl> |
f0b843c1 RL |
293 | |
294 | Utility to list and display certificates, keys, CRLs, etc. | |
295 | ||
dfee8626 | 296 | =item B<ts> |
21e8bbf2 | 297 | |
c4de074e | 298 | Time Stamping Authority tool (client/server). |
21e8bbf2 | 299 | |
dfee8626 | 300 | =item B<verify> |
aba3e65f DSH |
301 | |
302 | X.509 Certificate Verification. | |
303 | ||
dfee8626 | 304 | =item B<version> |
aba3e65f DSH |
305 | |
306 | OpenSSL Version Information. | |
307 | ||
dfee8626 | 308 | =item B<x509> |
aba3e65f DSH |
309 | |
310 | X.509 Certificate Data Management. | |
311 | ||
312 | =back | |
313 | ||
05ea606a | 314 | =head2 Message Digest Commands |
aba3e65f | 315 | |
e1271ac2 | 316 | =over 4 |
aba3e65f | 317 | |
4b7c6385 KR |
318 | =item B<blake2b512> |
319 | ||
320 | BLAKE2b-512 Digest | |
321 | ||
322 | =item B<blake2s256> | |
323 | ||
324 | BLAKE2s-256 Digest | |
325 | ||
aba3e65f DSH |
326 | =item B<md2> |
327 | ||
328 | MD2 Digest | |
329 | ||
4b7c6385 KR |
330 | =item B<md4> |
331 | ||
332 | MD4 Digest | |
333 | ||
aba3e65f DSH |
334 | =item B<md5> |
335 | ||
336 | MD5 Digest | |
337 | ||
338 | =item B<mdc2> | |
339 | ||
340 | MDC2 Digest | |
341 | ||
342 | =item B<rmd160> | |
343 | ||
344 | RMD-160 Digest | |
345 | ||
4c583c36 | 346 | =item B<sha1> |
aba3e65f DSH |
347 | |
348 | SHA-1 Digest | |
349 | ||
c7503f52 AP |
350 | =item B<sha224> |
351 | ||
4b7c6385 | 352 | SHA-2 224 Digest |
c7503f52 AP |
353 | |
354 | =item B<sha256> | |
355 | ||
4b7c6385 | 356 | SHA-2 256 Digest |
c7503f52 AP |
357 | |
358 | =item B<sha384> | |
359 | ||
4b7c6385 | 360 | SHA-2 384 Digest |
c7503f52 AP |
361 | |
362 | =item B<sha512> | |
363 | ||
4b7c6385 KR |
364 | SHA-2 512 Digest |
365 | ||
366 | =item B<sha3-224> | |
367 | ||
368 | SHA-3 224 Digest | |
369 | ||
370 | =item B<sha3-256> | |
371 | ||
372 | SHA-3 256 Digest | |
373 | ||
374 | =item B<sha3-384> | |
375 | ||
376 | SHA-3 384 Digest | |
377 | ||
378 | =item B<sha3-512> | |
379 | ||
380 | SHA-3 512 Digest | |
381 | ||
382 | =item B<shake128> | |
383 | ||
384 | SHA-3 SHAKE128 Digest | |
385 | ||
386 | =item B<shake256> | |
387 | ||
388 | SHA-3 SHAKE256 Digest | |
389 | ||
390 | =item B<sm3> | |
391 | ||
392 | SM3 Digest | |
c7503f52 | 393 | |
677741f8 AP |
394 | =back |
395 | ||
22bb8c25 | 396 | =head2 Encryption, Decryption, and Encoding Commands |
aba3e65f | 397 | |
1362190b AS |
398 | The following aliases provide convenient access to the most used encodings |
399 | and ciphers. | |
400 | ||
401 | Depending on how OpenSSL was configured and built, not all ciphers listed | |
d86925e6 | 402 | here may be present. See L<openssl-enc(1)> for more information. |
1362190b | 403 | |
e1271ac2 | 404 | =over 4 |
aba3e65f | 405 | |
1362190b AS |
406 | =item B<aes128>, B<aes-128-cbc>, B<aes-128-cfb>, B<aes-128-ctr>, B<aes-128-ecb>, B<aes-128-ofb> |
407 | ||
408 | AES-128 Cipher | |
409 | ||
410 | =item B<aes192>, B<aes-192-cbc>, B<aes-192-cfb>, B<aes-192-ctr>, B<aes-192-ecb>, B<aes-192-ofb> | |
411 | ||
412 | AES-192 Cipher | |
413 | ||
414 | =item B<aes256>, B<aes-256-cbc>, B<aes-256-cfb>, B<aes-256-ctr>, B<aes-256-ecb>, B<aes-256-ofb> | |
415 | ||
416 | AES-256 Cipher | |
417 | ||
418 | =item B<aria128>, B<aria-128-cbc>, B<aria-128-cfb>, B<aria-128-ctr>, B<aria-128-ecb>, B<aria-128-ofb> | |
419 | ||
420 | Aria-128 Cipher | |
421 | ||
422 | =item B<aria192>, B<aria-192-cbc>, B<aria-192-cfb>, B<aria-192-ctr>, B<aria-192-ecb>, B<aria-192-ofb> | |
423 | ||
424 | Aria-192 Cipher | |
425 | ||
426 | =item B<aria256>, B<aria-256-cbc>, B<aria-256-cfb>, B<aria-256-ctr>, B<aria-256-ecb>, B<aria-256-ofb> | |
427 | ||
428 | Aria-256 Cipher | |
429 | ||
aba3e65f DSH |
430 | =item B<base64> |
431 | ||
432 | Base64 Encoding | |
433 | ||
dfee8626 | 434 | =item B<bf>, B<bf-cbc>, B<bf-cfb>, B<bf-ecb>, B<bf-ofb> |
aba3e65f DSH |
435 | |
436 | Blowfish Cipher | |
437 | ||
1362190b AS |
438 | =item B<camellia128>, B<camellia-128-cbc>, B<camellia-128-cfb>, B<camellia-128-ctr>, B<camellia-128-ecb>, B<camellia-128-ofb> |
439 | ||
440 | Camellia-128 Cipher | |
441 | ||
442 | =item B<camellia192>, B<camellia-192-cbc>, B<camellia-192-cfb>, B<camellia-192-ctr>, B<camellia-192-ecb>, B<camellia-192-ofb> | |
443 | ||
444 | Camellia-192 Cipher | |
445 | ||
446 | =item B<camellia256>, B<camellia-256-cbc>, B<camellia-256-cfb>, B<camellia-256-ctr>, B<camellia-256-ecb>, B<camellia-256-ofb> | |
447 | ||
448 | Camellia-256 Cipher | |
449 | ||
dfee8626 | 450 | =item B<cast>, B<cast-cbc> |
aba3e65f DSH |
451 | |
452 | CAST Cipher | |
453 | ||
dfee8626 | 454 | =item B<cast5-cbc>, B<cast5-cfb>, B<cast5-ecb>, B<cast5-ofb> |
aba3e65f DSH |
455 | |
456 | CAST5 Cipher | |
457 | ||
1362190b AS |
458 | =item B<chacha20> |
459 | ||
460 | Chacha20 Cipher | |
461 | ||
dfee8626 | 462 | =item B<des>, B<des-cbc>, B<des-cfb>, B<des-ecb>, B<des-ede>, B<des-ede-cbc>, B<des-ede-cfb>, B<des-ede-ofb>, B<des-ofb> |
aba3e65f DSH |
463 | |
464 | DES Cipher | |
465 | ||
dfee8626 | 466 | =item B<des3>, B<desx>, B<des-ede3>, B<des-ede3-cbc>, B<des-ede3-cfb>, B<des-ede3-ofb> |
aba3e65f DSH |
467 | |
468 | Triple-DES Cipher | |
469 | ||
dfee8626 | 470 | =item B<idea>, B<idea-cbc>, B<idea-cfb>, B<idea-ecb>, B<idea-ofb> |
aba3e65f DSH |
471 | |
472 | IDEA Cipher | |
473 | ||
dfee8626 | 474 | =item B<rc2>, B<rc2-cbc>, B<rc2-cfb>, B<rc2-ecb>, B<rc2-ofb> |
aba3e65f DSH |
475 | |
476 | RC2 Cipher | |
477 | ||
478 | =item B<rc4> | |
479 | ||
480 | RC4 Cipher | |
481 | ||
dfee8626 | 482 | =item B<rc5>, B<rc5-cbc>, B<rc5-cfb>, B<rc5-ecb>, B<rc5-ofb> |
aba3e65f DSH |
483 | |
484 | RC5 Cipher | |
485 | ||
1362190b AS |
486 | =item B<seed>, B<seed-cbc>, B<seed-cfb>, B<seed-ecb>, B<seed-ofb> |
487 | ||
488 | SEED Cipher | |
489 | ||
490 | =item B<sm4>, B<sm4-cbc>, B<sm4-cfb>, B<sm4-ctr>, B<sm4-ecb>, B<sm4-ofb> | |
491 | ||
492 | SM4 Cipher | |
493 | ||
aba3e65f DSH |
494 | =back |
495 | ||
3dfda1a6 | 496 | =head1 OPTIONS |
0634424f RS |
497 | |
498 | Details of which options are available depend on the specific command. | |
77a795e4 | 499 | This section describes some common options with common behavior. |
0634424f RS |
500 | |
501 | =head2 Common Options | |
502 | ||
e1271ac2 | 503 | =over 4 |
0634424f RS |
504 | |
505 | =item B<-help> | |
506 | ||
507 | Provides a terse summary of all options. | |
a397aca4 RS |
508 | If an option takes an argument, the "type" of argument is also given. |
509 | ||
510 | =item B<--> | |
511 | ||
512 | This terminates the list of options. It is mostly useful if any filename | |
513 | parameters start with a minus sign: | |
514 | ||
515 | openssl verify [flags...] -- -cert1.pem... | |
0634424f RS |
516 | |
517 | =back | |
518 | ||
777182a0 RS |
519 | =head2 Format Options |
520 | ||
521 | Several OpenSSL commands can take input or generate output in a variety | |
522 | of formats. The list of acceptable formats, and the default, is | |
523 | described in each command documentation. The list of formats is | |
524 | described below. Both uppercase and lowercase are accepted. | |
525 | ||
526 | =over 4 | |
527 | ||
528 | =item B<DER> | |
529 | ||
530 | A binary format, encoded or parsed according to Distinguished Encoding Rules | |
531 | (DER) of the ASN.1 data language. | |
532 | ||
533 | =item B<ENGINE> | |
534 | ||
535 | Used to specify that the cryptographic material is in an OpenSSL B<engine>. | |
536 | An engine must be configured or specified using the B<-engine> option. | |
537 | In addition, the B<-input> flag can be used to name a specific object in | |
538 | the engine. | |
539 | A password, such as the B<-passin> flag often must be specified as well. | |
540 | ||
541 | =item B<P12> | |
542 | ||
543 | A DER-encoded file containing a PKCS#12 object. | |
544 | It might be necessary to provide a decryption password to retrieve | |
545 | the private key. | |
546 | ||
547 | =item B<PEM> | |
548 | ||
549 | A text format defined in IETF RFC 1421 and IETF RFC 7468. Briefly, this is | |
550 | a block of base-64 encoding (defined in IETF RFC 4648), with specific | |
551 | lines used to mark the start and end: | |
552 | ||
553 | Text before the BEGIN line is ignored. | |
554 | ----- BEGIN object-type ----- | |
555 | OT43gQKBgQC/2OHZoko6iRlNOAQ/tMVFNq7fL81GivoQ9F1U0Qr+DH3ZfaH8eIkX | |
556 | xT0ToMPJUzWAn8pZv0snA0um6SIgvkCuxO84OkANCVbttzXImIsL7pFzfcwV/ERK | |
557 | UM6j0ZuSMFOCr/lGPAoOQU0fskidGEHi1/kW+suSr28TqsyYZpwBDQ== | |
558 | ----- END object-type ----- | |
559 | Text after the END line is also ignored | |
560 | ||
561 | The I<object-type> must match the type of object that is expected. | |
562 | For example a C<BEGIN X509 CERTIFICATE> will not match if the command | |
563 | is trying to read a private key. The types supported include: | |
564 | ||
565 | ANY PRIVATE KEY | |
566 | CERTIFICATE | |
567 | CERTIFICATE REQUEST | |
568 | CMS | |
569 | DH PARAMETERS | |
570 | DSA PARAMETERS | |
571 | DSA PUBLIC KEY | |
572 | EC PARAMETERS | |
573 | EC PRIVATE KEY | |
574 | ECDSA PUBLIC KEY | |
575 | ENCRYPTED PRIVATE KEY | |
576 | PARAMETERS | |
577 | PKCS #7 SIGNED DATA | |
578 | PKCS7 | |
579 | PRIVATE KEY | |
580 | PUBLIC KEY | |
581 | RSA PRIVATE KEY | |
582 | SSL SESSION PARAMETERS | |
583 | TRUSTED CERTIFICATE | |
584 | X509 CRL | |
585 | X9.42 DH PARAMETERS | |
586 | ||
587 | The following legacy I<object-type>'s are also supported for compatibility | |
588 | with earlier releases: | |
589 | ||
590 | DSA PRIVATE KEY | |
591 | NEW CERTIFICATE REQUEST | |
592 | RSA PUBLIC KEY | |
593 | X509 CERTIFICATE | |
594 | ||
595 | =item B<SMIME> | |
596 | ||
597 | An S/MIME object as described in IETF RFC 8551. | |
598 | Earlier versions were known as CMS and are compatible. | |
599 | Note that the parsing is simple and might fail to parse some legal data. | |
600 | ||
601 | =back | |
602 | ||
603 | The options to specify the format are as follows. Refer to the individual | |
604 | manpage to see which options are accepted. | |
605 | ||
606 | =over 4 | |
607 | ||
608 | =item B<-inform> I<format>, B<-outform> I<format> | |
609 | ||
610 | The format of the input or output streams. | |
611 | ||
612 | =item B<-keyform> I<format> | |
613 | ||
614 | Format of a private key input source. | |
615 | ||
9fcb9702 | 616 | =item B<-CRLform> I<format> |
777182a0 RS |
617 | |
618 | Format of a CRL input source. | |
619 | ||
620 | =back | |
621 | ||
0634424f | 622 | =head2 Pass Phrase Options |
a3fe382e DSH |
623 | |
624 | Several commands accept password arguments, typically using B<-passin> | |
625 | and B<-passout> for input and output passwords respectively. These allow | |
626 | the password to be obtained from a variety of sources. Both of these | |
627 | options take a single argument whose format is described below. If no | |
628 | password argument is given and a password is required then the user is | |
629 | prompted to enter one: this will typically be read from the current | |
630 | terminal with echoing turned off. | |
631 | ||
84814344 RL |
632 | Note that character encoding may be relevant, please see |
633 | L<passphrase-encoding(7)>. | |
634 | ||
e1271ac2 | 635 | =over 4 |
a3fe382e | 636 | |
2f0ea936 | 637 | =item B<pass:>I<password> |
a3fe382e | 638 | |
2f0ea936 | 639 | The actual password is I<password>. Since the password is visible |
a3fe382e DSH |
640 | to utilities (like 'ps' under Unix) this form should only be used |
641 | where security is not important. | |
642 | ||
2f0ea936 | 643 | =item B<env:>I<var> |
a3fe382e | 644 | |
2f0ea936 | 645 | Obtain the password from the environment variable I<var>. Since |
a3fe382e DSH |
646 | the environment of other processes is visible on certain platforms |
647 | (e.g. ps under certain Unix OSes) this option should be used with caution. | |
648 | ||
2f0ea936 | 649 | =item B<file:>I<pathname> |
a3fe382e | 650 | |
2f0ea936 | 651 | The first line of I<pathname> is the password. If the same I<pathname> |
a3fe382e DSH |
652 | argument is supplied to B<-passin> and B<-passout> arguments then the first |
653 | line will be used for the input password and the next line for the output | |
2f0ea936 | 654 | password. I<pathname> need not refer to a regular file: it could for example |
a3fe382e DSH |
655 | refer to a device or named pipe. |
656 | ||
2f0ea936 | 657 | =item B<fd:>I<number> |
a3fe382e | 658 | |
2f0ea936 | 659 | Read the password from the file descriptor I<number>. This can be used to |
a3fe382e DSH |
660 | send the data via a pipe for example. |
661 | ||
662 | =item B<stdin> | |
663 | ||
c4de074e | 664 | Read the password from standard input. |
a3fe382e DSH |
665 | |
666 | =back | |
667 | ||
a397aca4 RS |
668 | =head2 Trusted Certificate Options |
669 | ||
670 | Part of validating a certificate includes verifying that the chain of CA's | |
671 | can be traced up to an existing trusted root. The following options specify | |
672 | how to list the trusted roots, also known as trust anchors. A collection | |
673 | of trusted roots is called a I<trust store>. | |
674 | ||
675 | Note that OpenSSL does not provide a default set of trust anchors. Many | |
676 | Linux distributions include a system default and configure OpenSSL to point | |
677 | to that. Mozilla maintains an influential trust store that can be found at | |
678 | L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>. | |
679 | ||
680 | =over 4 | |
681 | ||
682 | =item B<-CAfile> I<file> | |
683 | ||
684 | Load the specified file which contains one or more PEM-format certificates | |
685 | of CA's that are trusted. | |
686 | ||
687 | =item B<-no-CAfile> | |
688 | ||
689 | Do not load the default file of trusted certificates. | |
690 | ||
691 | =item B<-CApath> I<dir> | |
692 | ||
693 | Use the specified directory as a list of trust certificates. That is, | |
694 | files should be named with the hash of the X.509 SubjectName of each | |
695 | certificate. This is so that the library can extract the IssuerName, | |
696 | hash it, and directly lookup the file to get the issuer certificate. | |
697 | See L<openssl-rehash(1)> for information on creating this type of directory. | |
698 | ||
699 | =item B<-no-CApath> | |
700 | ||
701 | Do not use the default directory of trusted certificates. | |
702 | ||
fd3397fc RL |
703 | =item B<-CAstore> I<uri> |
704 | ||
705 | Use I<uri> as a store of trusted CA certificates. The URI may | |
706 | indicate a single certificate, as well as a collection of them. | |
707 | With URIs in the C<file:> scheme, this acts as B<-CAfile> or | |
708 | B<-CApath>, depending on if the URI indicates a single file or | |
709 | directory. | |
710 | See L<ossl_store-file(7)> for more information on the C<file:> scheme. | |
711 | ||
712 | These certificates are also used when building the server certificate | |
713 | chain (for example with L<openssl-s_server(1)>) or client certificate | |
714 | chain (for example with L<openssl-s_time(1)>). | |
715 | ||
716 | =item B<-no-CAstore> | |
717 | ||
718 | Do not use the default store. | |
719 | ||
a397aca4 RS |
720 | =back |
721 | ||
722 | =head2 Random State Options | |
723 | ||
724 | Prior to OpenSSL 3.0, it was common for applications to store information | |
725 | about the state of the random-number generator in a file that was loaded | |
726 | at startup and rewritten upon exit. On modern operating systems, this is | |
727 | generally no longer necessary as OpenSSL will seed itself from the | |
728 | appropriate CPU flags, device files, and so on. These flags are still | |
729 | supported for special platforms or circumstances that might require them. | |
730 | ||
731 | It is generally an error to use the same seed file more than once and | |
732 | every use of B<-rand> should be paired with B<-writerand>. | |
733 | ||
734 | =over 4 | |
735 | ||
736 | =item B<-rand> I<files> | |
737 | ||
738 | A file or files containing random data used to seed the random number | |
739 | generator. | |
740 | Multiple files can be specified separated by an OS-dependent character. | |
741 | The separator is C<;> for MS-Windows, C<,> for OpenVMS, and C<:> for | |
742 | all others. Another way to specify multiple files is to repeat this flag | |
743 | with different filenames. | |
744 | ||
745 | =item B<-writerand> I<file> | |
746 | ||
747 | Writes the seed data to the specified I<file> upon exit. | |
748 | This file can be used in a subsequent command invocation. | |
749 | ||
750 | =back | |
751 | ||
9fcb9702 RS |
752 | =head2 Extended Verification Options |
753 | ||
754 | Sometimes there may be more than one certificate chain leading to an | |
755 | end-entity certificate. | |
756 | This usually happens when a root or intermediate CA signs a certificate | |
757 | for another a CA in other organization. | |
758 | Another reason is when a CA might have intermediates that use two different | |
759 | signature formats, such as a SHA-1 and a SHA-256 digest. | |
760 | ||
761 | The following options can be used to provide data that will allow the | |
762 | OpenSSL command to generate an alternative chain. | |
763 | ||
764 | =over 4 | |
765 | ||
766 | =item B<-xchain_build> | |
767 | ||
768 | Specify whether the application should build the certificate chain to be | |
769 | provided to the server for the extra certificates via the B<-xkey>, | |
770 | B<-xcert>, and B<-xchain> options. | |
771 | ||
772 | =item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain> | |
773 | ||
774 | Specify an extra certificate, private key and certificate chain. These behave | |
775 | in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When | |
776 | specified, the callback returning the first valid chain will be in use by the | |
777 | client. | |
778 | ||
779 | =item B<-xcertform> B<DER>|B<PEM>, B<-xkeyform> B<DER>|B<PEM> | |
780 | ||
79c44b4e | 781 | The input format for the extra certificate and key, respectively. |
9fcb9702 RS |
782 | See L<openssl(1)/Format Options> for details. |
783 | ||
784 | =back | |
785 | ||
bc24e3ee RS |
786 | =head2 Name Format Options |
787 | ||
788 | OpenSSL provides fine-grain control over how the subject and issuer DN's are | |
789 | displayed. | |
790 | This is specified by using the B<-nameopt> option, which takes a | |
791 | comma-separated list of options from the following set. | |
792 | An option may be preceeded by a minus sign, C<->, to turn it off. | |
793 | The default value is C<oneline>. | |
794 | The first four are the most commonly used. | |
795 | ||
796 | =over 4 | |
797 | ||
798 | =item B<compat> | |
799 | ||
800 | Display the name using an old format from previous OpenSSL versions. | |
801 | ||
802 | =item B<RFC2253> | |
803 | ||
804 | Display the name using the format defined in RFC 2253. | |
805 | It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, | |
806 | B<dump_nostr>, B<dump_unknown>, B<dump_der>, B<sep_comma_plus>, B<dn_rev> | |
807 | and B<sname>. | |
808 | ||
809 | =item B<oneline> | |
810 | ||
811 | Display the name in one line, using a format that is more readable | |
812 | RFC 2253. | |
813 | It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, | |
814 | B<dump_nostr>, B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, | |
815 | B<space_eq> and B<sname> options. | |
816 | ||
817 | =item B<multiline> | |
818 | ||
819 | Display the name using multiple lines. | |
820 | It is equivalent to B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, B<space_eq>, | |
821 | B<lname> and B<align>. | |
822 | ||
823 | =item B<esc_2253> | |
824 | ||
825 | Escape the "special" characters in a field, as required by RFC 2253. | |
826 | That is, any of the characters C<,+"E<lt>E<gt>;>, C<#> at the beginning of | |
827 | a string and leading or trailing spaces. | |
828 | ||
829 | =item B<esc_2254> | |
830 | ||
831 | Escape the "special" characters in a field as required by RFC 2254 in a field. | |
832 | That is, the B<NUL> character and and of C<()*>. | |
833 | ||
834 | =item B<esc_ctrl> | |
835 | ||
836 | Escape non-printable ASCII characters, codes less than 0x20 (space) | |
837 | or greater than 0x7F (DELETE). They are displayed using RFC 2253 C<\XX> | |
838 | notation where B<XX> are the two hex digits representing the character value. | |
839 | ||
840 | =item B<esc_msb> | |
841 | ||
842 | Escape any characters with the most significant bit set, that is with | |
843 | values larger than 127, as described in B<esc_ctrl>. | |
844 | ||
845 | =item B<use_quote> | |
846 | ||
847 | Escapes some characters by surrounding the entire string with quotation | |
848 | marks, C<">. | |
849 | Without this option, individual special characters are preceeded with | |
850 | a backslash character, C<\>. | |
851 | ||
852 | =item B<utf8> | |
853 | ||
854 | Convert all strings to UTF-8 format first as required by RFC 2253. | |
855 | If the output device is UTF-8 compatible, then using this option (and | |
856 | not setting B<esc_msb>) may give the correct display of multibyte | |
857 | characters. | |
858 | If this option is not set, then multibyte characters larger than 0xFF | |
859 | will be output as C<\UXXXX> for 16 bits or C<\WXXXXXXXX> for 32 bits. | |
860 | In addition, any UTF8Strings will be converted to their character form first. | |
861 | ||
862 | =item B<ignore_type> | |
863 | ||
864 | This option does not attempt to interpret multibyte characters in any | |
865 | way. That is, the content octets are merely dumped as though one octet | |
866 | represents each character. This is useful for diagnostic purposes but | |
867 | will result in rather odd looking output. | |
868 | ||
869 | =item B<show_type> | |
870 | ||
871 | Display the type of the ASN1 character string before the value, | |
872 | such as C<BMPSTRING: Hello World>. | |
873 | ||
874 | =item B<dump_der> | |
875 | ||
876 | Any fields that would be output in hex format are displayed using | |
877 | the DER encoding of the field. | |
878 | If not set, just the content octets are displayed. | |
879 | Either way, the B<#XXXX...> format of RFC 2253 is used. | |
880 | ||
881 | =item B<dump_nostr> | |
882 | ||
883 | Dump non-character strings, such as ASN.1 B<OCTET STRING>. | |
884 | If this option is not set, then non character string types will be displayed | |
885 | as though each content octet represents a single character. | |
886 | ||
887 | =item B<dump_all> | |
888 | ||
889 | Dump all fields. When this used with B<dump_der>, this allows the | |
890 | DER encoding of the structure to be unambiguously determined. | |
891 | ||
892 | =item B<dump_unknown> | |
893 | ||
894 | Dump any field whose OID is not recognised by OpenSSL. | |
895 | ||
896 | =item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, | |
897 | B<sep_multiline> | |
898 | ||
899 | Specify the field separators. The first word is used between the | |
900 | Relative Distinguished Names (RDNs) and the second is between | |
901 | multiple Attribute Value Assertions (AVAs). Multiple AVAs are | |
902 | very rare and their use is discouraged. | |
903 | The options ending in "space" additionally place a space after the separator to make it more readable. | |
904 | The B<sep_multiline> starts each field on its own line, and uses "plus space" | |
905 | for the AVA separator. | |
906 | It also indents the fields by four characters. | |
907 | The default value is B<sep_comma_plus_space>. | |
908 | ||
909 | =item B<dn_rev> | |
910 | ||
911 | Reverse the fields of the DN as required by RFC 2253. | |
912 | This also reverses the order of multiple AVAs in a field, but this is | |
913 | permissible as there is no ordering on values. | |
914 | ||
915 | =item B<nofname>, B<sname>, B<lname>, B<oid> | |
916 | ||
917 | Specify how the field name is displayed. | |
918 | B<nofname> does not display the field at all. | |
919 | B<sname> uses the "short name" form (CN for commonName for example). | |
920 | B<lname> uses the long form. | |
921 | B<oid> represents the OID in numerical form and is useful for | |
922 | diagnostic purpose. | |
923 | ||
924 | =item B<align> | |
925 | ||
926 | Align field values for a more readable output. Only usable with | |
927 | B<sep_multiline>. | |
928 | ||
929 | =item B<space_eq> | |
930 | ||
931 | Places spaces round the equal sign, C<=>, character which follows the field | |
932 | name. | |
933 | ||
934 | =back | |
935 | ||
018aaeb4 RS |
936 | =head2 Engine Options |
937 | ||
938 | =over 4 | |
939 | ||
940 | =item B<-engine> I<id> | |
941 | ||
942 | Use the engine identified by I<id> and use all the methods it | |
943 | implements (algorithms, key storage, etc.), unless specified otherwise in | |
944 | the command-specific documentation or it is configured to do so, as described | |
945 | in L<config(5)/Engine Configuration Module>. | |
946 | ||
947 | =back | |
948 | ||
0b836c21 RL |
949 | =head1 ENVIRONMENT |
950 | ||
22bb8c25 RS |
951 | The OpenSSL library can be take some configuration parameters from the |
952 | environment. Some of these variables are listed below. For information | |
953 | about specific commands, see L<openssl-engine(1)>, L<openssl-provider(1)>, | |
954 | L<openssl-rehash(1)>, and L<tsget(1)>. | |
955 | ||
956 | For information about the use of environment variables in configuration, | |
957 | see L<config(5)/ENVIRONMENT>. | |
958 | ||
959 | For information about querying or specifying CPU architecture flags, see | |
960 | L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>. | |
961 | ||
962 | For information about all environment variables used by the OpenSSL libraries, | |
963 | see L<openssl-env(7)>. | |
964 | ||
0b836c21 RL |
965 | =over 4 |
966 | ||
fed8bd90 | 967 | =item B<OPENSSL_TRACE=>I<name>[,...] |
0b836c21 RL |
968 | |
969 | Enable tracing output of OpenSSL library, by name. | |
970 | This output will only make sense if you know OpenSSL internals well. | |
971 | Also, it might not give you any output at all, depending on how | |
972 | OpenSSL was built. | |
973 | ||
974 | The value is a comma separated list of names, with the following | |
975 | available: | |
976 | ||
977 | =over 4 | |
978 | ||
979 | =item B<TRACE> | |
980 | ||
981 | The tracing functionality. | |
982 | ||
983 | =item B<TLS> | |
984 | ||
985 | General SSL/TLS. | |
986 | ||
987 | =item B<TLS_CIPHER> | |
988 | ||
989 | SSL/TLS cipher. | |
990 | ||
991 | =item B<ENGINE_CONF> | |
992 | ||
993 | ENGINE configuration. | |
994 | ||
995 | =item B<ENGINE_TABLE> | |
996 | ||
997 | The function that is used by RSA, DSA (etc) code to select registered | |
998 | ENGINEs, cache defaults and functional references (etc), will generate | |
999 | debugging summaries. | |
1000 | ||
1001 | =item B<ENGINE_REF_COUNT> | |
1002 | ||
1003 | Reference counts in the ENGINE structure will be monitored with a line | |
1004 | of generated for each change. | |
1005 | ||
1006 | =item B<PKCS5V2> | |
1007 | ||
1008 | PKCS#5 v2 keygen. | |
1009 | ||
1010 | =item B<PKCS12_KEYGEN> | |
1011 | ||
1012 | PKCS#12 key generation. | |
1013 | ||
1014 | =item B<PKCS12_DECRYPT> | |
1015 | ||
1016 | PKCS#12 decryption. | |
1017 | ||
1018 | =item B<X509V3_POLICY> | |
1019 | ||
1020 | Generates the complete policy tree at various point during X.509 v3 | |
1021 | policy evaluation. | |
1022 | ||
1023 | =item B<BN_CTX> | |
1024 | ||
1025 | BIGNUM context. | |
1026 | ||
1027 | =back | |
1028 | ||
1029 | =back | |
1030 | ||
aba3e65f DSH |
1031 | =head1 SEE ALSO |
1032 | ||
b6b66573 DMSP |
1033 | L<openssl-asn1parse(1)>, |
1034 | L<openssl-ca(1)>, | |
1035 | L<openssl-ciphers(1)>, | |
1036 | L<openssl-cms(1)>, | |
1037 | L<openssl-crl(1)>, | |
1038 | L<openssl-crl2pkcs7(1)>, | |
1039 | L<openssl-dgst(1)>, | |
1040 | L<openssl-dhparam(1)>, | |
1041 | L<openssl-dsa(1)>, | |
1042 | L<openssl-dsaparam(1)>, | |
1043 | L<openssl-ec(1)>, | |
1044 | L<openssl-ecparam(1)>, | |
1045 | L<openssl-enc(1)>, | |
1046 | L<openssl-engine(1)>, | |
1047 | L<openssl-errstr(1)>, | |
1048 | L<openssl-gendsa(1)>, | |
1049 | L<openssl-genpkey(1)>, | |
1050 | L<openssl-genrsa(1)>, | |
1051 | L<openssl-kdf(1)>, | |
1052 | L<openssl-mac(1)>, | |
1053 | L<openssl-nseq(1)>, | |
1054 | L<openssl-ocsp(1)>, | |
1055 | L<openssl-passwd(1)>, | |
1056 | L<openssl-pkcs12(1)>, | |
1057 | L<openssl-pkcs7(1)>, | |
1058 | L<openssl-pkcs8(1)>, | |
1059 | L<openssl-pkey(1)>, | |
1060 | L<openssl-pkeyparam(1)>, | |
1061 | L<openssl-pkeyutl(1)>, | |
1062 | L<openssl-prime(1)>, | |
1063 | L<openssl-rand(1)>, | |
1064 | L<openssl-rehash(1)>, | |
1065 | L<openssl-req(1)>, | |
1066 | L<openssl-rsa(1)>, | |
1067 | L<openssl-rsautl(1)>, | |
1068 | L<openssl-s_client(1)>, | |
1069 | L<openssl-s_server(1)>, | |
1070 | L<openssl-s_time(1)>, | |
1071 | L<openssl-sess_id(1)>, | |
1072 | L<openssl-smime(1)>, | |
1073 | L<openssl-speed(1)>, | |
1074 | L<openssl-spkac(1)>, | |
1075 | L<openssl-srp(1)>, | |
1076 | L<openssl-storeutl(1)>, | |
1077 | L<openssl-ts(1)>, | |
1078 | L<openssl-verify(1)>, | |
1079 | L<openssl-version(1)>, | |
1080 | L<openssl-x509(1)>, | |
1081 | L<config(5)>, | |
1082 | L<crypto(7)>, | |
22bb8c25 | 1083 | L<openssl-env(7)>. |
b6b66573 DMSP |
1084 | L<ssl(7)>, |
1085 | L<x509v3_config(5)> | |
1086 | ||
aba3e65f DSH |
1087 | |
1088 | =head1 HISTORY | |
1089 | ||
2f0ea936 | 1090 | The B<list> -I<XXX>B<-algorithms> options were added in OpenSSL 1.0.0; |
88220dcb BM |
1091 | For notes on the availability of other commands, see their individual |
1092 | manual pages. | |
aba3e65f | 1093 | |
e2f92610 RS |
1094 | =head1 COPYRIGHT |
1095 | ||
c54492ec | 1096 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 1097 | |
449040b4 | 1098 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
1099 | this file except in compliance with the License. You can obtain a copy |
1100 | in the file LICENSE in the source distribution or at | |
1101 | L<https://www.openssl.org/source/license.html>. | |
1102 | ||
1103 | =cut |