Use OSSL_STORE for load_{,pub}key() and load_cert() in apps/lib/apps.c
[openssl.git] / doc / man1 / openssl.pod
1 =pod
2
3 =head1 NAME
4
5 openssl - OpenSSL command line program
6
7 =head1 SYNOPSIS
8
9 B<openssl>
10 I<command>
11 [ I<options> ... ]
12 [ I<parameters> ... ]
13
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>
23
24 B<openssl> B<no->I<XXX> [ I<options> ]
25
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 program for using the various
33 cryptography functions of OpenSSL's B<crypto> library from the shell.
34 It can be used for
35
36  o  Creation and management of private keys, public keys and parameters
37  o  Public key cryptographic operations
38  o  Creation of X.509 certificates, CSRs and CRLs
39  o  Calculation of Message Digests and Message Authentication Codes
40  o  Encryption and Decryption with Ciphers
41  o  SSL/TLS Client and Server Tests
42  o  Handling of S/MIME signed or encrypted mail
43  o  Timestamp requests, generation and verification
44
45 =head1 COMMAND SUMMARY
46
47 The B<openssl> program provides a rich variety of commands (I<command> in
48 the L</SYNOPSIS> above).
49 Each command can have many options and argument parameters, shown above as
50 I<options> and I<parameters>.
51
52 Detailed documentation and use cases for most standard subcommands are available
53 (e.g., L<openssl-x509(1)>).
54
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.
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.
60 The environment variable B<OPENSSL_CONF> can be used to specify
61 a different location of the file.
62 See L<openssl-env(7)>.
63
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
66 of all standard commands, message digest commands, or cipher commands,
67 respectively, that are available.
68
69 The list parameters B<-cipher-algorithms>, B<-digest-algorithms>,
70 and B<-mac-algorithms> list all cipher, message digest, and message
71 authentication code names, one entry per line. Aliases are listed as:
72
73  from => to
74
75 The list parameter B<-public-key-algorithms> lists all supported public
76 key algorithms.
77
78 The command B<no->I<XXX> tests whether a command of the
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>,
87 B<list>, or B<no->I<XXX> itself.)
88
89 =head2 Standard Commands
90
91 =over 4
92
93 =item B<asn1parse>
94
95 Parse an ASN.1 sequence.
96
97 =item B<ca>
98
99 Certificate Authority (CA) Management.
100
101 =item B<ciphers>
102
103 Cipher Suite Description Determination.
104
105 =item B<cms>
106
107 CMS (Cryptographic Message Syntax) command.
108
109 =item B<crl>
110
111 Certificate Revocation List (CRL) Management.
112
113 =item B<crl2pkcs7>
114
115 CRL to PKCS#7 Conversion.
116
117 =item B<dgst>
118
119 Message Digest calculation. MAC calculations are superseded by
120 L<openssl-mac(1)>.
121
122 =item B<dhparam>
123
124 Generation and Management of Diffie-Hellman Parameters. Superseded by
125 L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>.
126
127 =item B<dsa>
128
129 DSA Data Management.
130
131 =item B<dsaparam>
132
133 DSA Parameter Generation and Management. Superseded by
134 L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>.
135
136 =item B<ec>
137
138 EC (Elliptic curve) key processing.
139
140 =item B<ecparam>
141
142 EC parameter manipulation and generation.
143
144 =item B<enc>
145
146 Encryption, decryption, and encoding.
147
148 =item B<engine>
149
150 Engine (loadable module) information and manipulation.
151
152 =item B<errstr>
153
154 Error Number to Error String Conversion.
155
156 =item B<fipsinstall>
157
158 FIPS configuration installation.
159
160 =item B<gendsa>
161
162 Generation of DSA Private Key from Parameters. Superseded by
163 L<openssl-genpkey(1)> and L<openssl-pkey(1)>.
164
165 =item B<genpkey>
166
167 Generation of Private Key or Parameters.
168
169 =item B<genrsa>
170
171 Generation of RSA Private Key. Superseded by L<openssl-genpkey(1)>.
172
173 =item B<help>
174
175 Display information about a command's options.
176
177 =item B<info>
178
179 Display diverse information built into the OpenSSL libraries.
180
181 =item B<kdf>
182
183 Key Derivation Functions.
184
185 =item B<list>
186
187 List algorithms and features.
188
189 =item B<mac>
190
191 Message Authentication Code Calculation.
192
193 =item B<nseq>
194
195 Create or examine a Netscape certificate sequence.
196
197 =item B<ocsp>
198
199 Online Certificate Status Protocol command.
200
201 =item B<passwd>
202
203 Generation of hashed passwords.
204
205 =item B<pkcs12>
206
207 PKCS#12 Data Management.
208
209 =item B<pkcs7>
210
211 PKCS#7 Data Management.
212
213 =item B<pkcs8>
214
215 PKCS#8 format private key conversion command.
216
217 =item B<pkey>
218
219 Public and private key management.
220
221 =item B<pkeyparam>
222
223 Public key algorithm parameter management.
224
225 =item B<pkeyutl>
226
227 Public key algorithm cryptographic operation command.
228
229 =item B<prime>
230
231 Compute prime numbers.
232
233 =item B<provider>
234
235 Load and query providers.
236
237 =item B<rand>
238
239 Generate pseudo-random bytes.
240
241 =item B<rehash>
242
243 Create symbolic links to certificate and CRL files named by the hash values.
244
245 =item B<req>
246
247 PKCS#10 X.509 Certificate Signing Request (CSR) Management.
248
249 =item B<rsa>
250
251 RSA key management.
252
253 =item B<rsautl>
254
255 RSA command for signing, verification, encryption, and decryption. Superseded
256 by  L<openssl-pkeyutl(1)>.
257
258 =item B<s_client>
259
260 This implements a generic SSL/TLS client which can establish a transparent
261 connection to a remote server speaking SSL/TLS. It's intended for testing
262 purposes only and provides only rudimentary interface functionality but
263 internally uses mostly all functionality of the OpenSSL B<ssl> library.
264
265 =item B<s_server>
266
267 This implements a generic SSL/TLS server which accepts connections from remote
268 clients speaking SSL/TLS. It's intended for testing purposes only and provides
269 only rudimentary interface functionality but internally uses mostly all
270 functionality of the OpenSSL B<ssl> library.  It provides both an own command
271 line oriented protocol for testing SSL functions and a simple HTTP response
272 facility to emulate an SSL/TLS-aware webserver.
273
274 =item B<s_time>
275
276 SSL Connection Timer.
277
278 =item B<sess_id>
279
280 SSL Session Data Management.
281
282 =item B<smime>
283
284 S/MIME mail processing.
285
286 =item B<speed>
287
288 Algorithm Speed Measurement.
289
290 =item B<spkac>
291
292 SPKAC printing and generating command.
293
294 =item B<srp>
295
296 Maintain SRP password file.
297
298 =item B<storeutl>
299
300 Command to list and display certificates, keys, CRLs, etc.
301
302 =item B<ts>
303
304 Time Stamping Authority command.
305
306 =item B<verify>
307
308 X.509 Certificate Verification.
309
310 =item B<version>
311
312 OpenSSL Version Information.
313
314 =item B<x509>
315
316 X.509 Certificate Data Management.
317
318 =back
319
320 =head2 Message Digest Commands
321
322 =over 4
323
324 =item B<blake2b512>
325
326 BLAKE2b-512 Digest
327
328 =item B<blake2s256>
329
330 BLAKE2s-256 Digest
331
332 =item B<md2>
333
334 MD2 Digest
335
336 =item B<md4>
337
338 MD4 Digest
339
340 =item B<md5>
341
342 MD5 Digest
343
344 =item B<mdc2>
345
346 MDC2 Digest
347
348 =item B<rmd160>
349
350 RMD-160 Digest
351
352 =item B<sha1>
353
354 SHA-1 Digest
355
356 =item B<sha224>
357
358 SHA-2 224 Digest
359
360 =item B<sha256>
361
362 SHA-2 256 Digest
363
364 =item B<sha384>
365
366 SHA-2 384 Digest
367
368 =item B<sha512>
369
370 SHA-2 512 Digest
371
372 =item B<sha3-224>
373
374 SHA-3 224 Digest
375
376 =item B<sha3-256>
377
378 SHA-3 256 Digest
379
380 =item B<sha3-384>
381
382 SHA-3 384 Digest
383
384 =item B<sha3-512>
385
386 SHA-3 512 Digest
387
388 =item B<shake128>
389
390 SHA-3 SHAKE128 Digest
391
392 =item B<shake256>
393
394 SHA-3 SHAKE256 Digest
395
396 =item B<sm3>
397
398 SM3 Digest
399
400 =back
401
402 =head2 Encryption, Decryption, and Encoding Commands
403
404 The following aliases provide convenient access to the most used encodings
405 and ciphers.
406
407 Depending on how OpenSSL was configured and built, not all ciphers listed
408 here may be present. See L<openssl-enc(1)> for more information.
409
410 =over 4
411
412 =item B<aes128>, B<aes-128-cbc>, B<aes-128-cfb>, B<aes-128-ctr>, B<aes-128-ecb>, B<aes-128-ofb>
413
414 AES-128 Cipher
415
416 =item B<aes192>, B<aes-192-cbc>, B<aes-192-cfb>, B<aes-192-ctr>, B<aes-192-ecb>, B<aes-192-ofb>
417
418 AES-192 Cipher
419
420 =item B<aes256>, B<aes-256-cbc>, B<aes-256-cfb>, B<aes-256-ctr>, B<aes-256-ecb>, B<aes-256-ofb>
421
422 AES-256 Cipher
423
424 =item B<aria128>, B<aria-128-cbc>, B<aria-128-cfb>, B<aria-128-ctr>, B<aria-128-ecb>, B<aria-128-ofb>
425
426 Aria-128 Cipher
427
428 =item B<aria192>, B<aria-192-cbc>, B<aria-192-cfb>, B<aria-192-ctr>, B<aria-192-ecb>, B<aria-192-ofb>
429
430 Aria-192 Cipher
431
432 =item B<aria256>, B<aria-256-cbc>, B<aria-256-cfb>, B<aria-256-ctr>, B<aria-256-ecb>, B<aria-256-ofb>
433
434 Aria-256 Cipher
435
436 =item B<base64>
437
438 Base64 Encoding
439
440 =item B<bf>, B<bf-cbc>, B<bf-cfb>, B<bf-ecb>, B<bf-ofb>
441
442 Blowfish Cipher
443
444 =item B<camellia128>, B<camellia-128-cbc>, B<camellia-128-cfb>, B<camellia-128-ctr>, B<camellia-128-ecb>, B<camellia-128-ofb>
445
446 Camellia-128 Cipher
447
448 =item B<camellia192>, B<camellia-192-cbc>, B<camellia-192-cfb>, B<camellia-192-ctr>, B<camellia-192-ecb>, B<camellia-192-ofb>
449
450 Camellia-192 Cipher
451
452 =item B<camellia256>, B<camellia-256-cbc>, B<camellia-256-cfb>, B<camellia-256-ctr>, B<camellia-256-ecb>, B<camellia-256-ofb>
453
454 Camellia-256 Cipher
455
456 =item B<cast>, B<cast-cbc>
457
458 CAST Cipher
459
460 =item B<cast5-cbc>, B<cast5-cfb>, B<cast5-ecb>, B<cast5-ofb>
461
462 CAST5 Cipher
463
464 =item B<chacha20>
465
466 Chacha20 Cipher
467
468 =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>
469
470 DES Cipher
471
472 =item B<des3>, B<desx>, B<des-ede3>, B<des-ede3-cbc>, B<des-ede3-cfb>, B<des-ede3-ofb>
473
474 Triple-DES Cipher
475
476 =item B<idea>, B<idea-cbc>, B<idea-cfb>, B<idea-ecb>, B<idea-ofb>
477
478 IDEA Cipher
479
480 =item B<rc2>, B<rc2-cbc>, B<rc2-cfb>, B<rc2-ecb>, B<rc2-ofb>
481
482 RC2 Cipher
483
484 =item B<rc4>
485
486 RC4 Cipher
487
488 =item B<rc5>, B<rc5-cbc>, B<rc5-cfb>, B<rc5-ecb>, B<rc5-ofb>
489
490 RC5 Cipher
491
492 =item B<seed>, B<seed-cbc>, B<seed-cfb>, B<seed-ecb>, B<seed-ofb>
493
494 SEED Cipher
495
496 =item B<sm4>, B<sm4-cbc>, B<sm4-cfb>, B<sm4-ctr>, B<sm4-ecb>, B<sm4-ofb>
497
498 SM4 Cipher
499
500 =back
501
502 =head1 OPTIONS
503
504 Details of which options are available depend on the specific command.
505 This section describes some common options with common behavior.
506
507 =head2 Common Options
508
509 =over 4
510
511 =item B<-help>
512
513 Provides a terse summary of all options.
514 If an option takes an argument, the "type" of argument is also given.
515
516 =item B<-->
517
518 This terminates the list of options. It is mostly useful if any filename
519 parameters start with a minus sign:
520
521  openssl verify [flags...] -- -cert1.pem...
522
523 =back
524
525 =head2 Format Options
526
527 Several OpenSSL commands can take input or generate output in a variety
528 of formats.
529 Since OpenSSL 3.0 keys, single certificates, and CRLs can be read from
530 files in any of the B<DER>, B<PEM>, or B<P12> formats,
531 while specifying their input format is no more needed.
532
533 The list of acceptable formats, and the default, is
534 described in each command documentation.  The list of formats is
535 described below. Both uppercase and lowercase are accepted.
536
537 =over 4
538
539 =item B<DER>
540
541 A binary format, encoded or parsed according to Distinguished Encoding Rules
542 (DER) of the ASN.1 data language.
543
544 =item B<ENGINE>
545
546 Used to specify that the cryptographic material is in an OpenSSL B<engine>.
547 An engine must be configured or specified using the B<-engine> option.
548 In addition, the B<-input> flag can be used to name a specific object in
549 the engine.
550 A password, such as the B<-passin> flag often must be specified as well.
551
552 =item B<P12>
553
554 A DER-encoded file containing a PKCS#12 object.
555 It might be necessary to provide a decryption password to retrieve
556 the private key.
557
558 =item B<PEM>
559
560 A text format defined in IETF RFC 1421 and IETF RFC 7468. Briefly, this is
561 a block of base-64 encoding (defined in IETF RFC 4648), with specific
562 lines used to mark the start and end:
563
564  Text before the BEGIN line is ignored.
565  ----- BEGIN object-type -----
566  OT43gQKBgQC/2OHZoko6iRlNOAQ/tMVFNq7fL81GivoQ9F1U0Qr+DH3ZfaH8eIkX
567  xT0ToMPJUzWAn8pZv0snA0um6SIgvkCuxO84OkANCVbttzXImIsL7pFzfcwV/ERK
568  UM6j0ZuSMFOCr/lGPAoOQU0fskidGEHi1/kW+suSr28TqsyYZpwBDQ==
569  ----- END object-type -----
570  Text after the END line is also ignored
571
572 The I<object-type> must match the type of object that is expected.
573 For example a C<BEGIN X509 CERTIFICATE> will not match if the command
574 is trying to read a private key. The types supported include:
575
576  ANY PRIVATE KEY
577  CERTIFICATE
578  CERTIFICATE REQUEST
579  CMS
580  DH PARAMETERS
581  DSA PARAMETERS
582  DSA PUBLIC KEY
583  EC PARAMETERS
584  EC PRIVATE KEY
585  ECDSA PUBLIC KEY
586  ENCRYPTED PRIVATE KEY
587  PARAMETERS
588  PKCS #7 SIGNED DATA
589  PKCS7
590  PRIVATE KEY
591  PUBLIC KEY
592  RSA PRIVATE KEY
593  SSL SESSION PARAMETERS
594  TRUSTED CERTIFICATE
595  X509 CRL
596  X9.42 DH PARAMETERS
597
598 The following legacy I<object-type>'s are also supported for compatibility
599 with earlier releases:
600
601  DSA PRIVATE KEY
602  NEW CERTIFICATE REQUEST
603  RSA PUBLIC KEY
604  X509 CERTIFICATE
605
606 =item B<SMIME>
607
608 An S/MIME object as described in IETF RFC 8551.
609 Earlier versions were known as CMS and are compatible.
610 Note that the parsing is simple and might fail to parse some legal data.
611
612 =back
613
614 The options to specify the format are as follows. Refer to the individual
615 manpage to see which options are accepted.
616
617 =over 4
618
619 =item B<-inform> I<format>, B<-outform> I<format>
620
621 The format of the input or output streams.
622
623 =item B<-keyform> I<format>
624
625 Format of a private key input source.
626 The only value with effect is B<ENGINE>; all others have become obsolete.
627 See L<openssl(1)/Format Options> for details.
628
629 =item B<-CRLform> I<format>
630
631 Format of a CRL input source.
632
633 =back
634
635 =head2 Pass Phrase Options
636
637 Several commands accept password arguments, typically using B<-passin>
638 and B<-passout> for input and output passwords respectively. These allow
639 the password to be obtained from a variety of sources. Both of these
640 options take a single argument whose format is described below. If no
641 password argument is given and a password is required then the user is
642 prompted to enter one: this will typically be read from the current
643 terminal with echoing turned off.
644
645 Note that character encoding may be relevant, please see
646 L<passphrase-encoding(7)>.
647
648 =over 4
649
650 =item B<pass:>I<password>
651
652 The actual password is I<password>. Since the password is visible
653 to utilities (like 'ps' under Unix) this form should only be used
654 where security is not important.
655
656 =item B<env:>I<var>
657
658 Obtain the password from the environment variable I<var>. Since
659 the environment of other processes is visible on certain platforms
660 (e.g. ps under certain Unix OSes) this option should be used with caution.
661
662 =item B<file:>I<pathname>
663
664 The first line of I<pathname> is the password. If the same I<pathname>
665 argument is supplied to B<-passin> and B<-passout> arguments then the first
666 line will be used for the input password and the next line for the output
667 password. I<pathname> need not refer to a regular file: it could for example
668 refer to a device or named pipe.
669
670 =item B<fd:>I<number>
671
672 Read the password from the file descriptor I<number>. This can be used to
673 send the data via a pipe for example.
674
675 =item B<stdin>
676
677 Read the password from standard input.
678
679 =back
680
681 =head2 Trusted Certificate Options
682
683 Part of validating a certificate includes verifying that the chain of CA's
684 can be traced up to an existing trusted root.  The following options specify
685 how to list the trusted roots, also known as trust anchors.  A collection
686 of trusted roots is called a I<trust store>.
687
688 Note that OpenSSL does not provide a default set of trust anchors.  Many
689 Linux distributions include a system default and configure OpenSSL to point
690 to that.  Mozilla maintains an influential trust store that can be found at
691 L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
692
693 =over 4
694
695 =item B<-CAfile> I<file>
696
697 Load the specified file which contains one or more PEM-format certificates
698 of CA's that are trusted.
699
700 =item B<-no-CAfile>
701
702 Do not load the default file of trusted certificates.
703
704 =item B<-CApath> I<dir>
705
706 Use the specified directory as a list of trust certificates. That is,
707 files should be named with the hash of the X.509 SubjectName of each
708 certificate. This is so that the library can extract the IssuerName,
709 hash it, and directly lookup the file to get the issuer certificate.
710 See L<openssl-rehash(1)> for information on creating this type of directory.
711
712 =item B<-no-CApath>
713
714 Do not use the default directory of trusted certificates.
715
716 =item B<-CAstore> I<uri>
717
718 Use I<uri> as a store of trusted CA certificates.  The URI may
719 indicate a single certificate, as well as a collection of them.
720 With URIs in the C<file:> scheme, this acts as B<-CAfile> or
721 B<-CApath>, depending on if the URI indicates a single file or
722 directory.
723 See L<ossl_store-file(7)> for more information on the C<file:> scheme.
724
725 These certificates are also used when building the server certificate
726 chain (for example with L<openssl-s_server(1)>) or client certificate
727 chain (for example with L<openssl-s_time(1)>).
728
729 =item B<-no-CAstore>
730
731 Do not use the default store.
732
733 =back
734
735 =head2 Random State Options
736
737 Prior to OpenSSL 1.1.1, it was common for applications to store information
738 about the state of the random-number generator in a file that was loaded
739 at startup and rewritten upon exit. On modern operating systems, this is
740 generally no longer necessary as OpenSSL will seed itself from a trusted
741 entropy source provided by the operating system. These flags are still
742 supported for special platforms or circumstances that might require them.
743
744 It is generally an error to use the same seed file more than once and
745 every use of B<-rand> should be paired with B<-writerand>.
746
747 =over 4
748
749 =item B<-rand> I<files>
750
751 A file or files containing random data used to seed the random number
752 generator.
753 Multiple files can be specified separated by an OS-dependent character.
754 The separator is C<;> for MS-Windows, C<,> for OpenVMS, and C<:> for
755 all others. Another way to specify multiple files is to repeat this flag
756 with different filenames.
757
758 =item B<-writerand> I<file>
759
760 Writes the seed data to the specified I<file> upon exit.
761 This file can be used in a subsequent command invocation.
762
763 =back
764
765 =head2 Provider Options
766
767 With the move to provider based cryptographic operations in OpenSSL 3.0,
768 options were added to allow specific providers or sets of providers to be used.
769
770 =over 4
771
772 =item B<-provider> I<name>
773
774 Use the provider identified by I<name> and use all the methods it
775 implements (algorithms, key storage, etc.).  This option can be specified
776 multiple time to load more than one provider.
777
778 =item B<-provider_path> I<path>
779
780 Specify the search I<path> that is used to locate provider modules.  The format
781 of I<path> varies depending on the operating system being used.
782
783 =back
784
785 =head2 Extended Verification Options
786
787 Sometimes there may be more than one certificate chain leading to an
788 end-entity certificate.
789 This usually happens when a root or intermediate CA signs a certificate
790 for another a CA in other organization.
791 Another reason is when a CA might have intermediates that use two different
792 signature formats, such as a SHA-1 and a SHA-256 digest.
793
794 The following options can be used to provide data that will allow the
795 OpenSSL command to generate an alternative chain.
796
797 =over 4
798
799 =item B<-xkey> I<infile>, B<-xcert> I<infile>, B<-xchain>
800
801 Specify an extra certificate, private key and certificate chain. These behave
802 in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options.  When
803 specified, the callback returning the first valid chain will be in use by the
804 client.
805
806 =item B<-xchain_build>
807
808 Specify whether the application should build the certificate chain to be
809 provided to the server for the extra certificates via the B<-xkey>,
810 B<-xcert>, and B<-xchain> options.
811
812 =item B<-xcertform> B<DER>|B<PEM>|B<P12>
813
814 The input format for the extra certificate.
815 This option has no effect and is retained for backward compatibility only.
816
817 =item B<-xkeyform> B<DER>|B<PEM>|B<P12>
818
819 The input format for the extra key.
820 This option has no effect and is retained for backward compatibility only.
821
822 =back
823
824 =head2 Verification Options
825
826 Many OpenSSL commands verify certificates. The details of how each
827 command handles errors are documented on the specific command page.
828
829 Verification is a complicated process, consisting of a number of separate
830 steps that are detailed in the following paragraphs.
831
832 First, a certificate chain is built up starting from the supplied certificate
833 and ending in a root CA.  It is an error if the whole chain cannot be
834 built up.  The chain is built up by looking up the certificate that
835 signed (or issued) the certificate. It then repeats the process, until
836 it gets to a certificate that is self-issued.
837
838 The process of looking up the issuer's certificate itself involves a number
839 of steps.  After all certificates whose subject name matches the issuer
840 name of the current certificate are subject to further tests.  The relevant
841 authority key identifier components of the current certificate (if present)
842 must match the subject key identifier (if present) and issuer and serial
843 number of the candidate issuer, in addition the keyUsage extension of the
844 candidate issuer (if present) must permit certificate signing.
845
846 The lookup first looks in the list of untrusted certificates and if no match
847 is found the remaining lookups are from the trusted certificates. The root CA
848 is always looked up in the trusted certificate list: if the certificate to
849 verify is a root certificate then an exact match must be found in the trusted
850 list.
851
852 The second step is to check every untrusted certificate's extensions
853 for consistency with the supplied purpose. If the B<-purpose> option is
854 not included then no checks are done. The supplied or "leaf" certificate
855 must have extensions compatible with the supplied purpose and all other
856 certificates must also be valid CA certificates. The precise extensions
857 required are described in more detail in
858 L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
859
860 The third step is to check the trust settings on the root CA. The root
861 CA should be trusted for the supplied purpose.  For compatibility with
862 previous versions of OpenSSL, a certificate with no trust settings is
863 considered to be valid for all purposes.
864
865 The fourth, and final, step is to check the validity of the certificate
866 chain. The validity period is checked against the system time
867 and the C<notBefore> and C<notAfter> dates in the certificate. The certificate
868 signatures are also checked at this point. The B<-attime> flag may be
869 used to specify a time other than "now."
870
871 If all operations complete successfully then certificate is considered
872 valid. If any operation fails then the certificate is not valid.
873
874 The details of the processing steps can be fine-tuned with the
875 following flags.
876
877 =over 4
878
879 =item B<-verbose>
880
881 Print extra information about the operations being performed.
882
883 =item B<-attime> I<timestamp>
884
885 Perform validation checks using time specified by I<timestamp> and not
886 current system time. I<timestamp> is the number of seconds since
887 January 1, 1970 (i.e., the Unix Epoch).
888
889 =item B<-no_check_time>
890
891 This option suppresses checking the validity period of certificates and CRLs
892 against the current time. If option B<-attime> is used to specify
893 a verification time, the check is not suppressed.
894
895 =item B<-x509_strict>
896
897 This disables non-compliant workarounds for broken certificates.
898
899 =item B<-ignore_critical>
900
901 Normally if an unhandled critical extension is present which is not
902 supported by OpenSSL the certificate is rejected (as required by RFC5280).
903 If this option is set critical extensions are ignored.
904
905 =item B<-issuer_checks>
906
907 Ignored.
908
909 =item B<-crl_check>
910
911 Checks end entity certificate validity by attempting to look up a valid CRL.
912 If a valid CRL cannot be found an error occurs.
913
914 =item B<-crl_check_all>
915
916 Checks the validity of B<all> certificates in the chain by attempting
917 to look up valid CRLs.
918
919 =item B<-use_deltas>
920
921 Enable support for delta CRLs.
922
923 =item B<-extended_crl>
924
925 Enable extended CRL features such as indirect CRLs and alternate CRL
926 signing keys.
927
928 =item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
929
930 Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
931 192 bit, or only 192 bit Level of Security respectively.
932 See RFC6460 for details. In particular the supported signature algorithms are
933 reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
934 P-256 and P-384.
935
936 =item B<-auth_level> I<level>
937
938 Set the certificate chain authentication security level to I<level>.
939 The authentication security level determines the acceptable signature and
940 public key strength when verifying certificate chains.  For a certificate
941 chain to validate, the public keys of all the certificates must meet the
942 specified security I<level>.  The signature algorithm security level is
943 enforced for all the certificates in the chain except for the chain's
944 I<trust anchor>, which is either directly trusted or validated by means
945 other than its signature.  See L<SSL_CTX_set_security_level(3)> for the
946 definitions of the available levels.  The default security level is -1,
947 or "not set".  At security level 0 or lower all algorithms are acceptable.
948 Security level 1 requires at least 80-bit-equivalent security and is broadly
949 interoperable, though it will, for example, reject MD5 signatures or RSA
950 keys shorter than 1024 bits.
951
952 =item B<-partial_chain>
953
954 Allow verification to succeed even if a I<complete> chain cannot be built to a
955 self-signed trust-anchor, provided it is possible to construct a chain to a
956 trusted certificate that might not be self-signed.
957
958 =item B<-check_ss_sig>
959
960 Verify the signature on the self-signed root CA. This is disabled by default
961 because it doesn't add any security.
962
963 =item B<-allow_proxy_certs>
964
965 Allow the verification of proxy certificates.
966
967 =item B<-trusted_first>
968
969 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
970
971 =item B<-no_alt_chains>
972
973 As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no
974 effect.
975
976 =item B<-trusted> I<file>
977
978 Parse I<file> as a set of one or more certificates in PEM format.
979 All certificates must be self-signed, unless the
980 B<-partial_chain> option is specified.
981 This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options
982 and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so
983 only certificates in the file are trust anchors.
984 This option may be used multiple times.
985
986 =item B<-untrusted> I<file>
987
988 Parse I<file> as a set of one or more certificates in PEM format.
989 All certificates are untrusted certificates that may be used to
990 construct a certificate chain from the subject certificate to a trust anchor.
991 This option may be used multiple times.
992
993 =item B<-policy> I<arg>
994
995 Enable policy processing and add I<arg> to the user-initial-policy-set (see
996 RFC5280). The policy I<arg> can be an object name an OID in numeric form.
997 This argument can appear more than once.
998
999 =item B<-explicit_policy>
1000
1001 Set policy variable require-explicit-policy (see RFC5280).
1002
1003 =item B<-policy_check>
1004
1005 Enables certificate policy processing.
1006
1007 =item B<-policy_print>
1008
1009 Print out diagnostics related to policy processing.
1010
1011 =item B<-inhibit_any>
1012
1013 Set policy variable inhibit-any-policy (see RFC5280).
1014
1015 =item B<-inhibit_map>
1016
1017 Set policy variable inhibit-policy-mapping (see RFC5280).
1018
1019 =item B<-purpose> I<purpose>
1020
1021 The intended use for the certificate. If this option is not specified, this
1022 command will not consider certificate purpose during chain verification.
1023 Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
1024 B<smimesign>, B<smimeencrypt>.
1025
1026 =item B<-verify_depth> I<num>
1027
1028 Limit the certificate chain to I<num> intermediate CA certificates.
1029 A maximal depth chain can have up to I<num>+2 certificates, since neither the
1030 end-entity certificate nor the trust-anchor certificate count against the
1031 B<-verify_depth> limit.
1032
1033 =item B<-verify_email> I<email>
1034
1035 Verify if I<email> matches the email address in Subject Alternative Name or
1036 the email in the subject Distinguished Name.
1037
1038 =item B<-verify_hostname> I<hostname>
1039
1040 Verify if I<hostname> matches DNS name in Subject Alternative Name or
1041 Common Name in the subject certificate.
1042
1043 =item B<-verify_ip> I<ip>
1044
1045 Verify if I<ip> matches the IP address in Subject Alternative Name of
1046 the subject certificate.
1047
1048 =item B<-verify_name> I<name>
1049
1050 Use default verification policies like trust model and required certificate
1051 policies identified by I<name>.
1052 The trust model determines which auxiliary trust or reject OIDs are applicable
1053 to verifying the given certificate chain.
1054 See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
1055 Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
1056 B<ssl_client>, B<ssl_server>.
1057 These mimics the combinations of purpose and trust settings used in SSL, CMS
1058 and S/MIME.
1059 As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
1060 specified, so the B<-verify_name> options are functionally equivalent to the
1061 corresponding B<-purpose> settings.
1062
1063 =back
1064
1065 =head2 Name Format Options
1066
1067 OpenSSL provides fine-grain control over how the subject and issuer DN's are
1068 displayed.
1069 This is specified by using the B<-nameopt> option, which takes a
1070 comma-separated list of options from the following set.
1071 An option may be preceded by a minus sign, C<->, to turn it off.
1072 The default value is C<oneline>.
1073 The first four are the most commonly used.
1074
1075 =over 4
1076
1077 =item B<compat>
1078
1079 Display the name using an old format from previous OpenSSL versions.
1080
1081 =item B<RFC2253>
1082
1083 Display the name using the format defined in RFC 2253.
1084 It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>,
1085 B<dump_nostr>, B<dump_unknown>, B<dump_der>, B<sep_comma_plus>, B<dn_rev>
1086 and B<sname>.
1087
1088 =item B<oneline>
1089
1090 Display the name in one line, using a format that is more readable
1091 RFC 2253.
1092 It is equivalent to B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>,
1093 B<dump_nostr>, B<dump_der>, B<use_quote>, B<sep_comma_plus_space>,
1094 B<space_eq> and B<sname> options.
1095
1096 =item B<multiline>
1097
1098 Display the name using multiple lines.
1099 It is equivalent to B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, B<space_eq>,
1100 B<lname> and B<align>.
1101
1102 =item B<esc_2253>
1103
1104 Escape the "special" characters in a field, as required by RFC 2253.
1105 That is, any of the characters C<,+"E<lt>E<gt>;>, C<#> at the beginning of
1106 a string and leading or trailing spaces.
1107
1108 =item B<esc_2254>
1109
1110 Escape the "special" characters in a field as required by RFC 2254 in a field.
1111 That is, the B<NUL> character and and of C<()*>.
1112
1113 =item B<esc_ctrl>
1114
1115 Escape non-printable ASCII characters, codes less than 0x20 (space)
1116 or greater than 0x7F (DELETE). They are displayed using RFC 2253 C<\XX>
1117 notation where B<XX> are the two hex digits representing the character value.
1118
1119 =item B<esc_msb>
1120
1121 Escape any characters with the most significant bit set, that is with
1122 values larger than 127, as described in B<esc_ctrl>.
1123
1124 =item B<use_quote>
1125
1126 Escapes some characters by surrounding the entire string with quotation
1127 marks, C<">.
1128 Without this option, individual special characters are preceded with
1129 a backslash character, C<\>.
1130
1131 =item B<utf8>
1132
1133 Convert all strings to UTF-8 format first as required by RFC 2253.
1134 If the output device is UTF-8 compatible, then using this option (and
1135 not setting B<esc_msb>) may give the correct display of multibyte
1136 characters.
1137 If this option is not set, then multibyte characters larger than 0xFF
1138 will be output as C<\UXXXX> for 16 bits or C<\WXXXXXXXX> for 32 bits.
1139 In addition, any UTF8Strings will be converted to their character form first.
1140
1141 =item B<ignore_type>
1142
1143 This option does not attempt to interpret multibyte characters in any
1144 way. That is, the content octets are merely dumped as though one octet
1145 represents each character. This is useful for diagnostic purposes but
1146 will result in rather odd looking output.
1147
1148 =item B<show_type>
1149
1150 Display the type of the ASN1 character string before the value,
1151 such as C<BMPSTRING: Hello World>.
1152
1153 =item B<dump_der>
1154
1155 Any fields that would be output in hex format are displayed using
1156 the DER encoding of the field.
1157 If not set, just the content octets are displayed.
1158 Either way, the B<#XXXX...> format of RFC 2253 is used.
1159
1160 =item B<dump_nostr>
1161
1162 Dump non-character strings, such as ASN.1 B<OCTET STRING>.
1163 If this option is not set, then non character string types will be displayed
1164 as though each content octet represents a single character.
1165
1166 =item B<dump_all>
1167
1168 Dump all fields. When this used with B<dump_der>, this allows the
1169 DER encoding of the structure to be unambiguously determined.
1170
1171 =item B<dump_unknown>
1172
1173 Dump any field whose OID is not recognised by OpenSSL.
1174
1175 =item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
1176 B<sep_multiline>
1177
1178 Specify the field separators. The first word is used between the
1179 Relative Distinguished Names (RDNs) and the second is between
1180 multiple Attribute Value Assertions (AVAs). Multiple AVAs are
1181 very rare and their use is discouraged.
1182 The options ending in "space" additionally place a space after the separator to make it more readable.
1183 The B<sep_multiline> starts each field on its own line, and uses "plus space"
1184 for the AVA separator.
1185 It also indents the fields by four characters.
1186 The default value is B<sep_comma_plus_space>.
1187
1188 =item B<dn_rev>
1189
1190 Reverse the fields of the DN as required by RFC 2253.
1191 This also reverses the order of multiple AVAs in a field, but this is
1192 permissible as there is no ordering on values.
1193
1194 =item B<nofname>, B<sname>, B<lname>, B<oid>
1195
1196 Specify how the field name is displayed.
1197 B<nofname> does not display the field at all.
1198 B<sname> uses the "short name" form (CN for commonName for example).
1199 B<lname> uses the long form.
1200 B<oid> represents the OID in numerical form and is useful for
1201 diagnostic purpose.
1202
1203 =item B<align>
1204
1205 Align field values for a more readable output. Only usable with
1206 B<sep_multiline>.
1207
1208 =item B<space_eq>
1209
1210 Places spaces round the equal sign, C<=>, character which follows the field
1211 name.
1212
1213 =back
1214
1215 =head2 TLS Version Options
1216
1217 Several commands use SSL, TLS, or DTLS. By default, the commands use TLS and
1218 clients will offer the lowest and highest protocol version they support,
1219 and servers will pick the highest version that the client offers that is also
1220 supported by the server.
1221
1222 The options below can be used to limit which protocol versions are used,
1223 and whether TCP (SSL and TLS) or UDP (DTLS) is used.
1224 Note that not all protocols and flags may be available, depending on how
1225 OpenSSL was built.
1226
1227 =over 4
1228
1229 =item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
1230
1231 These options require or disable the use of the specified SSL or TLS protocols.
1232 When a specific TLS version is required, only that version will be offered or
1233 accepted.
1234 Only one specific protocol can be given and it cannot be combined with any of
1235 the B<no_> options.
1236
1237 =item B<-dtls>, B<-dtls1>, B<-dtls1_2>
1238
1239 These options specify to use DTLS instead of DLTS.
1240 With B<-dtls>, clients will negotiate any supported DTLS protocol version.
1241 Use the B<-dtls1> or B<-dtls1_2> options to support only DTLS1.0 or DTLS1.2,
1242 respectively.
1243
1244 =back
1245
1246 =head2 Engine Options
1247
1248 =over 4
1249
1250 =item B<-engine> I<id>
1251
1252 Use the engine identified by I<id> and use all the methods it
1253 implements (algorithms, key storage, etc.), unless specified otherwise in
1254 the command-specific documentation or it is configured to do so, as described
1255 in L<config(5)/Engine Configuration Module>.
1256
1257 =back
1258
1259 =head1 ENVIRONMENT
1260
1261 The OpenSSL library can be take some configuration parameters from the
1262 environment.  Some of these variables are listed below.  For information
1263 about specific commands, see L<openssl-engine(1)>, L<openssl-provider(1)>,
1264 L<openssl-rehash(1)>, and L<tsget(1)>.
1265
1266 For information about the use of environment variables in configuration,
1267 see L<config(5)/ENVIRONMENT>.
1268
1269 For information about querying or specifying CPU architecture flags, see
1270 L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>.
1271
1272 For information about all environment variables used by the OpenSSL libraries,
1273 see L<openssl-env(7)>.
1274
1275 =over 4
1276
1277 =item B<OPENSSL_TRACE=>I<name>[,...]
1278
1279 Enable tracing output of OpenSSL library, by name.
1280 This output will only make sense if you know OpenSSL internals well.
1281 Also, it might not give you any output at all, depending on how
1282 OpenSSL was built.
1283
1284 The value is a comma separated list of names, with the following
1285 available:
1286
1287 =over 4
1288
1289 =item B<TRACE>
1290
1291 The tracing functionality.
1292
1293 =item B<TLS>
1294
1295 General SSL/TLS.
1296
1297 =item B<TLS_CIPHER>
1298
1299 SSL/TLS cipher.
1300
1301 =item B<ENGINE_CONF>
1302
1303 ENGINE configuration.
1304
1305 =item B<ENGINE_TABLE>
1306
1307 The function that is used by RSA, DSA (etc) code to select registered
1308 ENGINEs, cache defaults and functional references (etc), will generate
1309 debugging summaries.
1310
1311 =item B<ENGINE_REF_COUNT>
1312
1313 Reference counts in the ENGINE structure will be monitored with a line
1314 of generated for each change.
1315
1316 =item B<PKCS5V2>
1317
1318 PKCS#5 v2 keygen.
1319
1320 =item B<PKCS12_KEYGEN>
1321
1322 PKCS#12 key generation.
1323
1324 =item B<PKCS12_DECRYPT>
1325
1326 PKCS#12 decryption.
1327
1328 =item B<X509V3_POLICY>
1329
1330 Generates the complete policy tree at various point during X.509 v3
1331 policy evaluation.
1332
1333 =item B<BN_CTX>
1334
1335 BIGNUM context.
1336
1337 =back
1338
1339 =back
1340
1341 =head1 SEE ALSO
1342
1343 L<openssl-asn1parse(1)>,
1344 L<openssl-ca(1)>,
1345 L<openssl-ciphers(1)>,
1346 L<openssl-cms(1)>,
1347 L<openssl-crl(1)>,
1348 L<openssl-crl2pkcs7(1)>,
1349 L<openssl-dgst(1)>,
1350 L<openssl-dhparam(1)>,
1351 L<openssl-dsa(1)>,
1352 L<openssl-dsaparam(1)>,
1353 L<openssl-ec(1)>,
1354 L<openssl-ecparam(1)>,
1355 L<openssl-enc(1)>,
1356 L<openssl-engine(1)>,
1357 L<openssl-errstr(1)>,
1358 L<openssl-gendsa(1)>,
1359 L<openssl-genpkey(1)>,
1360 L<openssl-genrsa(1)>,
1361 L<openssl-kdf(1)>,
1362 L<openssl-mac(1)>,
1363 L<openssl-nseq(1)>,
1364 L<openssl-ocsp(1)>,
1365 L<openssl-passwd(1)>,
1366 L<openssl-pkcs12(1)>,
1367 L<openssl-pkcs7(1)>,
1368 L<openssl-pkcs8(1)>,
1369 L<openssl-pkey(1)>,
1370 L<openssl-pkeyparam(1)>,
1371 L<openssl-pkeyutl(1)>,
1372 L<openssl-prime(1)>,
1373 L<openssl-rand(1)>,
1374 L<openssl-rehash(1)>,
1375 L<openssl-req(1)>,
1376 L<openssl-rsa(1)>,
1377 L<openssl-rsautl(1)>,
1378 L<openssl-s_client(1)>,
1379 L<openssl-s_server(1)>,
1380 L<openssl-s_time(1)>,
1381 L<openssl-sess_id(1)>,
1382 L<openssl-smime(1)>,
1383 L<openssl-speed(1)>,
1384 L<openssl-spkac(1)>,
1385 L<openssl-srp(1)>,
1386 L<openssl-storeutl(1)>,
1387 L<openssl-ts(1)>,
1388 L<openssl-verify(1)>,
1389 L<openssl-version(1)>,
1390 L<openssl-x509(1)>,
1391 L<config(5)>,
1392 L<crypto(7)>,
1393 L<openssl-env(7)>.
1394 L<ssl(7)>,
1395 L<x509v3_config(5)>
1396
1397
1398 =head1 HISTORY
1399
1400 The B<list> -I<XXX>B<-algorithms> options were added in OpenSSL 1.0.0;
1401 For notes on the availability of other commands, see their individual
1402 manual pages.
1403
1404 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
1405 is silently ignored.
1406
1407 The B<-xcertform> and B<-xkeyform> options
1408 are obsolete since OpenSSL 3.0.0 and have no effect.
1409
1410 =head1 COPYRIGHT
1411
1412 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
1413
1414 Licensed under the Apache License 2.0 (the "License").  You may not use
1415 this file except in compliance with the License.  You can obtain a copy
1416 in the file LICENSE in the source distribution or at
1417 L<https://www.openssl.org/source/license.html>.
1418
1419 =cut