doc/man1/openssl.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 openssl - OpenSSL command line tool
   6
   7 =head1 SYNOPSIS
   8
   9 B<openssl>
  10 I<command>
  11 [ I<command_opts> ... ]
  12 [ I<command_args> ... ]
  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<arbitrary 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 tool 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 sub-commands (I<command> in
  48 the SYNOPSIS above), each of which often has a wealth of options and arguments
  49 (I<command_opts> and I<command_args> in the SYNOPSIS).
  50
  51 Detailed documentation and use cases for most standard subcommands are available
  52 (e.g., L<x509(1)> or L<openssl-x509(1)>).
  53
  54 Many commands use an external configuration file for some or all of their
  55 arguments and have a B<-config> option to specify that file.
  56 The environment variable B<OPENSSL_CONF> can be used to specify
  57 the location of the file.
  58 If the environment variable is not specified, then the file is named
  59 F<openssl.cnf> in the default certificate storage area, whose value
  60 depends on the configuration flags specified when the OpenSSL
  61 was built.
  62
  63 The list options B<-standard-commands>, B<-digest-commands>,
  64 and B<-cipher-commands> output a list (one entry per line) of the names
  65 of all standard commands, message digest commands, or cipher commands,
  66 respectively, that are available.
  67
  68 The list parameters B<-cipher-algorithms>, B<-digest-algorithms>,
  69 and B<-mac-algorithms> list all cipher, message digest, and message
  70 authentication code names, one entry per line. Aliases are listed as:
  71
  72  from => to
  73
  74 The list parameter B<-public-key-algorithms> lists all supported public
  75 key algorithms.
  76
  77 The command B<no->I<XXX> tests whether a command of the
  78 specified name is available.  If no command named I<XXX> exists, it
  79 returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
  80 and prints I<XXX>.  In both cases, the output goes to B<stdout> and
  81 nothing is printed to B<stderr>.  Additional command line arguments
  82 are always ignored.  Since for each cipher there is a command of the
  83 same name, this provides an easy way for shell scripts to test for the
  84 availability of ciphers in the B<openssl> program.  (B<no->I<XXX> is
  85 not able to detect pseudo-commands such as B<quit>,
  86 B<list>, or B<no->I<XXX> itself.)
  87
  88 =head2 Standard Sub-commands
  89
  90 =over 4
  91
  92 =item B<asn1parse>
  93
  94 Parse an ASN.1 sequence.
  95
  96 =item B<ca>
  97
  98 Certificate Authority (CA) Management.
  99
 100 =item B<ciphers>
 101
 102 Cipher Suite Description Determination.
 103
 104 =item B<cms>
 105
 106 CMS (Cryptographic Message Syntax) utility.
 107
 108 =item B<crl>
 109
 110 Certificate Revocation List (CRL) Management.
 111
 112 =item B<crl2pkcs7>
 113
 114 CRL to PKCS#7 Conversion.
 115
 116 =item B<dgst>
 117
 118 Message Digest calculation. MAC calculations are superseded by
 119 L<openssl-mac(1)>.
 120
 121 =item B<dh>
 122
 123 Diffie-Hellman Parameter Management.
 124 Obsoleted by L<openssl-dhparam(1)>.
 125
 126 =item B<dhparam>
 127
 128 Generation and Management of Diffie-Hellman Parameters. Superseded by
 129 L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>.
 130
 131 =item B<dsa>
 132
 133 DSA Data Management.
 134
 135 =item B<dsaparam>
 136
 137 DSA Parameter Generation and Management. Superseded by
 138 L<openssl-genpkey(1)> and L<openssl-pkeyparam(1)>.
 139
 140 =item B<ec>
 141
 142 EC (Elliptic curve) key processing.
 143
 144 =item B<ecparam>
 145
 146 EC parameter manipulation and generation.
 147
 148 =item B<enc>
 149
 150 Encoding with Ciphers.
 151
 152 =item B<engine>
 153
 154 Engine (loadable module) information and manipulation.
 155
 156 =item B<errstr>
 157
 158 Error Number to Error String Conversion.
 159
 160 =item B<gendh>
 161
 162 Generation of Diffie-Hellman Parameters.
 163 Obsoleted by L<openssl-dhparam(1)>.
 164
 165 =item B<gendsa>
 166
 167 Generation of DSA Private Key from Parameters. Superseded by
 168 L<openssl-genpkey(1)> and L<openssl-pkey(1)>.
 169
 170 =item B<genpkey>
 171
 172 Generation of Private Key or Parameters.
 173
 174 =item B<genrsa>
 175
 176 Generation of RSA Private Key. Superseded by L<openssl-genpkey(1)>.
 177
 178 =item B<info>
 179
 180 Display diverse information built into the OpenSSL libraries.
 181
 182 =item B<kdf>
 183
 184 Key Derivation Functions.
 185
 186 =item B<mac>
 187
 188 Message Authentication Code Calculation.
 189
 190 =item B<nseq>
 191
 192 Create or examine a Netscape certificate sequence.
 193
 194 =item B<ocsp>
 195
 196 Online Certificate Status Protocol utility.
 197
 198 =item B<passwd>
 199
 200 Generation of hashed passwords.
 201
 202 =item B<pkcs12>
 203
 204 PKCS#12 Data Management.
 205
 206 =item B<pkcs7>
 207
 208 PKCS#7 Data Management.
 209
 210 =item B<pkcs8>
 211
 212 PKCS#8 format private key conversion tool.
 213
 214 =item B<pkey>
 215
 216 Public and private key management.
 217
 218 =item B<pkeyparam>
 219
 220 Public key algorithm parameter management.
 221
 222 =item B<pkeyutl>
 223
 224 Public key algorithm cryptographic operation utility.
 225
 226 =item B<prime>
 227
 228 Compute prime numbers.
 229
 230 =item B<rand>
 231
 232 Generate pseudo-random bytes.
 233
 234 =item B<rehash>
 235
 236 Create symbolic links to certificate and CRL files named by the hash values.
 237
 238 =item B<req>
 239
 240 PKCS#10 X.509 Certificate Signing Request (CSR) Management.
 241
 242 =item B<rsa>
 243
 244 RSA key management.
 245
 246 =item B<rsautl>
 247
 248 RSA utility for signing, verification, encryption, and decryption. Superseded
 249 by  L<openssl-pkeyutl(1)>.
 250
 251 =item B<s_client>
 252
 253 This implements a generic SSL/TLS client which can establish a transparent
 254 connection to a remote server speaking SSL/TLS. It's intended for testing
 255 purposes only and provides only rudimentary interface functionality but
 256 internally uses mostly all functionality of the OpenSSL B<ssl> library.
 257
 258 =item B<s_server>
 259
 260 This implements a generic SSL/TLS server which accepts connections from remote
 261 clients speaking SSL/TLS. It's intended for testing purposes only and provides
 262 only rudimentary interface functionality but internally uses mostly all
 263 functionality of the OpenSSL B<ssl> library.  It provides both an own command
 264 line oriented protocol for testing SSL functions and a simple HTTP response
 265 facility to emulate an SSL/TLS-aware webserver.
 266
 267 =item B<s_time>
 268
 269 SSL Connection Timer.
 270
 271 =item B<sess_id>
 272
 273 SSL Session Data Management.
 274
 275 =item B<smime>
 276
 277 S/MIME mail processing.
 278
 279 =item B<speed>
 280
 281 Algorithm Speed Measurement.
 282
 283 =item B<spkac>
 284
 285 SPKAC printing and generating utility.
 286
 287 =item B<srp>
 288
 289 Maintain SRP password file.
 290
 291 =item B<storeutl>
 292
 293 Utility to list and display certificates, keys, CRLs, etc.
 294
 295 =item B<ts>
 296
 297 Time Stamping Authority tool (client/server).
 298
 299 =item B<verify>
 300
 301 X.509 Certificate Verification.
 302
 303 =item B<version>
 304
 305 OpenSSL Version Information.
 306
 307 =item B<x509>
 308
 309 X.509 Certificate Data Management.
 310
 311 =back
 312
 313 =head2 Message Digest Commands
 314
 315 =over 4
 316
 317 =item B<blake2b512>
 318
 319 BLAKE2b-512 Digest
 320
 321 =item B<blake2s256>
 322
 323 BLAKE2s-256 Digest
 324
 325 =item B<md2>
 326
 327 MD2 Digest
 328
 329 =item B<md4>
 330
 331 MD4 Digest
 332
 333 =item B<md5>
 334
 335 MD5 Digest
 336
 337 =item B<mdc2>
 338
 339 MDC2 Digest
 340
 341 =item B<rmd160>
 342
 343 RMD-160 Digest
 344
 345 =item B<sha1>
 346
 347 SHA-1 Digest
 348
 349 =item B<sha224>
 350
 351 SHA-2 224 Digest
 352
 353 =item B<sha256>
 354
 355 SHA-2 256 Digest
 356
 357 =item B<sha384>
 358
 359 SHA-2 384 Digest
 360
 361 =item B<sha512>
 362
 363 SHA-2 512 Digest
 364
 365 =item B<sha3-224>
 366
 367 SHA-3 224 Digest
 368
 369 =item B<sha3-256>
 370
 371 SHA-3 256 Digest
 372
 373 =item B<sha3-384>
 374
 375 SHA-3 384 Digest
 376
 377 =item B<sha3-512>
 378
 379 SHA-3 512 Digest
 380
 381 =item B<shake128>
 382
 383 SHA-3 SHAKE128 Digest
 384
 385 =item B<shake256>
 386
 387 SHA-3 SHAKE256 Digest
 388
 389 =item B<sm3>
 390
 391 SM3 Digest
 392
 393 =back
 394
 395 =head2 Encoding and Cipher Commands
 396
 397 The following aliases provide convenient access to the most used encodings
 398 and ciphers.
 399
 400 Depending on how OpenSSL was configured and built, not all ciphers listed
 401 here may be present. See L<openssl-enc(1)> for more information and command
 402 usage.
 403
 404 =over 4
 405
 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
 430 =item B<base64>
 431
 432 Base64 Encoding
 433
 434 =item B<bf>, B<bf-cbc>, B<bf-cfb>, B<bf-ecb>, B<bf-ofb>
 435
 436 Blowfish Cipher
 437
 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
 450 =item B<cast>, B<cast-cbc>
 451
 452 CAST Cipher
 453
 454 =item B<cast5-cbc>, B<cast5-cfb>, B<cast5-ecb>, B<cast5-ofb>
 455
 456 CAST5 Cipher
 457
 458 =item B<chacha20>
 459
 460 Chacha20 Cipher
 461
 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>
 463
 464 DES Cipher
 465
 466 =item B<des3>, B<desx>, B<des-ede3>, B<des-ede3-cbc>, B<des-ede3-cfb>, B<des-ede3-ofb>
 467
 468 Triple-DES Cipher
 469
 470 =item B<idea>, B<idea-cbc>, B<idea-cfb>, B<idea-ecb>, B<idea-ofb>
 471
 472 IDEA Cipher
 473
 474 =item B<rc2>, B<rc2-cbc>, B<rc2-cfb>, B<rc2-ecb>, B<rc2-ofb>
 475
 476 RC2 Cipher
 477
 478 =item B<rc4>
 479
 480 RC4 Cipher
 481
 482 =item B<rc5>, B<rc5-cbc>, B<rc5-cfb>, B<rc5-ecb>, B<rc5-ofb>
 483
 484 RC5 Cipher
 485
 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
 494 =back
 495
 496 =head1 OPTIONS
 497
 498 Details of which options are available depend on the specific command.
 499 This section describes some common options with common behavior.
 500
 501 =head2 Common Options
 502
 503 =over 4
 504
 505 =item B<-help>
 506
 507 Provides a terse summary of all options.
 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...
 516
 517 =back
 518
 519 =head2 Pass Phrase Options
 520
 521 Several commands accept password arguments, typically using B<-passin>
 522 and B<-passout> for input and output passwords respectively. These allow
 523 the password to be obtained from a variety of sources. Both of these
 524 options take a single argument whose format is described below. If no
 525 password argument is given and a password is required then the user is
 526 prompted to enter one: this will typically be read from the current
 527 terminal with echoing turned off.
 528
 529 Note that character encoding may be relevant, please see
 530 L<passphrase-encoding(7)>.
 531
 532 =over 4
 533
 534 =item B<pass:>I<password>
 535
 536 The actual password is I<password>. Since the password is visible
 537 to utilities (like 'ps' under Unix) this form should only be used
 538 where security is not important.
 539
 540 =item B<env:>I<var>
 541
 542 Obtain the password from the environment variable I<var>. Since
 543 the environment of other processes is visible on certain platforms
 544 (e.g. ps under certain Unix OSes) this option should be used with caution.
 545
 546 =item B<file:>I<pathname>
 547
 548 The first line of I<pathname> is the password. If the same I<pathname>
 549 argument is supplied to B<-passin> and B<-passout> arguments then the first
 550 line will be used for the input password and the next line for the output
 551 password. I<pathname> need not refer to a regular file: it could for example
 552 refer to a device or named pipe.
 553
 554 =item B<fd:>I<number>
 555
 556 Read the password from the file descriptor I<number>. This can be used to
 557 send the data via a pipe for example.
 558
 559 =item B<stdin>
 560
 561 Read the password from standard input.
 562
 563 =back
 564
 565 =head2 Trusted Certificate Options
 566
 567 Part of validating a certificate includes verifying that the chain of CA's
 568 can be traced up to an existing trusted root.  The following options specify
 569 how to list the trusted roots, also known as trust anchors.  A collection
 570 of trusted roots is called a I<trust store>.
 571
 572 Note that OpenSSL does not provide a default set of trust anchors.  Many
 573 Linux distributions include a system default and configure OpenSSL to point
 574 to that.  Mozilla maintains an influential trust store that can be found at
 575 L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
 576
 577 =over 4
 578
 579 =item B<-CAfile> I<file>
 580
 581 Load the specified file which contains one or more PEM-format certificates
 582 of CA's that are trusted.
 583
 584 =item B<-no-CAfile>
 585
 586 Do not load the default file of trusted certificates.
 587
 588 =item B<-CApath> I<dir>
 589
 590 Use the specified directory as a list of trust certificates. That is,
 591 files should be named with the hash of the X.509 SubjectName of each
 592 certificate. This is so that the library can extract the IssuerName,
 593 hash it, and directly lookup the file to get the issuer certificate.
 594 See L<openssl-rehash(1)> for information on creating this type of directory.
 595
 596 =item B<-no-CApath>
 597
 598 Do not use the default directory of trusted certificates.
 599
 600 =back
 601
 602 =head2 Random State Options
 603
 604 Prior to OpenSSL 3.0, it was common for applications to store information
 605 about the state of the random-number generator in a file that was loaded
 606 at startup and rewritten upon exit. On modern operating systems, this is
 607 generally no longer necessary as OpenSSL will seed itself from the
 608 appropriate CPU flags, device files, and so on. These flags are still
 609 supported for special platforms or circumstances that might require them.
 610
 611 It is generally an error to use the same seed file more than once and
 612 every use of B<-rand> should be paired with B<-writerand>.
 613
 614 =over 4
 615
 616 =item B<-rand> I<files>
 617
 618 A file or files containing random data used to seed the random number
 619 generator.
 620 Multiple files can be specified separated by an OS-dependent character.
 621 The separator is C<;> for MS-Windows, C<,> for OpenVMS, and C<:> for
 622 all others. Another way to specify multiple files is to repeat this flag
 623 with different filenames.
 624
 625 =item B<-writerand> I<file>
 626
 627 Writes the seed data to the specified I<file> upon exit.
 628 This file can be used in a subsequent command invocation.
 629
 630 =back
 631
 632 =head1 ENVIRONMENT
 633
 634 =over 4
 635
 636 =item B<OPENSSL_TRACE=>I<name>[,...]
 637
 638 Enable tracing output of OpenSSL library, by name.
 639 This output will only make sense if you know OpenSSL internals well.
 640 Also, it might not give you any output at all, depending on how
 641 OpenSSL was built.
 642
 643 The value is a comma separated list of names, with the following
 644 available:
 645
 646 =over 4
 647
 648 =item B<TRACE>
 649
 650 The tracing functionality.
 651
 652 =item B<TLS>
 653
 654 General SSL/TLS.
 655
 656 =item B<TLS_CIPHER>
 657
 658 SSL/TLS cipher.
 659
 660 =item B<ENGINE_CONF>
 661
 662 ENGINE configuration.
 663
 664 =item B<ENGINE_TABLE>
 665
 666 The function that is used by RSA, DSA (etc) code to select registered
 667 ENGINEs, cache defaults and functional references (etc), will generate
 668 debugging summaries.
 669
 670 =item B<ENGINE_REF_COUNT>
 671
 672 Reference counts in the ENGINE structure will be monitored with a line
 673 of generated for each change.
 674
 675 =item B<PKCS5V2>
 676
 677 PKCS#5 v2 keygen.
 678
 679 =item B<PKCS12_KEYGEN>
 680
 681 PKCS#12 key generation.
 682
 683 =item B<PKCS12_DECRYPT>
 684
 685 PKCS#12 decryption.
 686
 687 =item B<X509V3_POLICY>
 688
 689 Generates the complete policy tree at various point during X.509 v3
 690 policy evaluation.
 691
 692 =item B<BN_CTX>
 693
 694 BIGNUM context.
 695
 696 =back
 697
 698 =back
 699
 700 =head1 SEE ALSO
 701
 702 L<openssl-asn1parse(1)>,
 703 L<openssl-ca(1)>,
 704 L<openssl-ciphers(1)>,
 705 L<openssl-cms(1)>,
 706 L<openssl-crl(1)>,
 707 L<openssl-crl2pkcs7(1)>,
 708 L<openssl-dgst(1)>,
 709 L<openssl-dhparam(1)>,
 710 L<openssl-dsa(1)>,
 711 L<openssl-dsaparam(1)>,
 712 L<openssl-ec(1)>,
 713 L<openssl-ecparam(1)>,
 714 L<openssl-enc(1)>,
 715 L<openssl-engine(1)>,
 716 L<openssl-errstr(1)>,
 717 L<openssl-gendsa(1)>,
 718 L<openssl-genpkey(1)>,
 719 L<openssl-genrsa(1)>,
 720 L<openssl-kdf(1)>,
 721 L<openssl-mac(1)>,
 722 L<openssl-nseq(1)>,
 723 L<openssl-ocsp(1)>,
 724 L<openssl-passwd(1)>,
 725 L<openssl-pkcs12(1)>,
 726 L<openssl-pkcs7(1)>,
 727 L<openssl-pkcs8(1)>,
 728 L<openssl-pkey(1)>,
 729 L<openssl-pkeyparam(1)>,
 730 L<openssl-pkeyutl(1)>,
 731 L<openssl-prime(1)>,
 732 L<openssl-rand(1)>,
 733 L<openssl-rehash(1)>,
 734 L<openssl-req(1)>,
 735 L<openssl-rsa(1)>,
 736 L<openssl-rsautl(1)>,
 737 L<openssl-s_client(1)>,
 738 L<openssl-s_server(1)>,
 739 L<openssl-s_time(1)>,
 740 L<openssl-sess_id(1)>,
 741 L<openssl-smime(1)>,
 742 L<openssl-speed(1)>,
 743 L<openssl-spkac(1)>,
 744 L<openssl-srp(1)>,
 745 L<openssl-storeutl(1)>,
 746 L<openssl-ts(1)>,
 747 L<openssl-verify(1)>,
 748 L<openssl-version(1)>,
 749 L<openssl-x509(1)>,
 750 L<config(5)>,
 751 L<crypto(7)>,
 752 L<ssl(7)>,
 753 L<x509v3_config(5)>
 754
 755
 756 =head1 HISTORY
 757
 758 The B<list> -I<XXX>B<-algorithms> options were added in OpenSSL 1.0.0;
 759 For notes on the availability of other commands, see their individual
 760 manual pages.
 761
 762 =head1 COPYRIGHT
 763
 764 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 765
 766 Licensed under the Apache License 2.0 (the "License").  You may not use
 767 this file except in compliance with the License.  You can obtain a copy
 768 in the file LICENSE in the source distribution or at
 769 L<https://www.openssl.org/source/license.html>.
 770
 771 =cut