diff options
-rw-r--r-- | src/usr.sbin/openssl/openssl.1 | 322 |
1 files changed, 255 insertions, 67 deletions
diff --git a/src/usr.sbin/openssl/openssl.1 b/src/usr.sbin/openssl/openssl.1 index d6114b68e6..5424b7a930 100644 --- a/src/usr.sbin/openssl/openssl.1 +++ b/src/usr.sbin/openssl/openssl.1 | |||
@@ -1,4 +1,4 @@ | |||
1 | .\" $OpenBSD: openssl.1,v 1.39 2004/04/06 13:47:34 jmc Exp $ | 1 | .\" $OpenBSD: openssl.1,v 1.40 2004/04/08 12:08:27 jmc Exp $ |
2 | .\" ==================================================================== | 2 | .\" ==================================================================== |
3 | .\" Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. | 3 | .\" Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. |
4 | .\" | 4 | .\" |
@@ -493,7 +493,7 @@ The format of this file is described in the | |||
493 | section below. | 493 | section below. |
494 | .It Fl out Ar file | 494 | .It Fl out Ar file |
495 | Output file to place the DER-encoded data into. | 495 | Output file to place the DER-encoded data into. |
496 | If this option is not present, then no encoded data will be output. | 496 | If this option is not present, no encoded data will be output. |
497 | This is most useful when combined with the | 497 | This is most useful when combined with the |
498 | .Fl strparse | 498 | .Fl strparse |
499 | option. | 499 | option. |
@@ -614,7 +614,7 @@ The output of some ASN.1 types is not well handled | |||
614 | .Op Fl extensions Ar section | 614 | .Op Fl extensions Ar section |
615 | .Op Fl extfile Ar section | 615 | .Op Fl extfile Ar section |
616 | .Op Fl in Ar file | 616 | .Op Fl in Ar file |
617 | .Op Fl key Ar arg | 617 | .Op Fl key Ar keyfile |
618 | .Op Fl keyfile Ar arg | 618 | .Op Fl keyfile Ar arg |
619 | .Op Fl keyform Ar PEM | ENGINE | 619 | .Op Fl keyform Ar PEM | ENGINE |
620 | .Op Fl md Ar arg | 620 | .Op Fl md Ar arg |
@@ -670,7 +670,7 @@ to be added when a certificate is issued (defaults to | |||
670 | unless the | 670 | unless the |
671 | .Fl extfile | 671 | .Fl extfile |
672 | option is used). | 672 | option is used). |
673 | If no extension section is present, then a V1 certificate is created. | 673 | If no extension section is present, a V1 certificate is created. |
674 | If the extension section is present | 674 | If the extension section is present |
675 | .Pq even if it is empty , | 675 | .Pq even if it is empty , |
676 | then a V3 certificate is created. | 676 | then a V3 certificate is created. |
@@ -688,7 +688,7 @@ containing a single certificate request to be signed by the CA. | |||
688 | .It Fl infiles | 688 | .It Fl infiles |
689 | If present, this should be the last option; all subsequent arguments | 689 | If present, this should be the last option; all subsequent arguments |
690 | are assumed to be the names of files containing certificate requests. | 690 | are assumed to be the names of files containing certificate requests. |
691 | .It Fl key Ar password | 691 | .It Fl key Ar keyfile |
692 | The password used to encrypt the private key. | 692 | The password used to encrypt the private key. |
693 | Since on some systems the command line arguments are visible | 693 | Since on some systems the command line arguments are visible |
694 | (e.g.\& | 694 | (e.g.\& |
@@ -1272,7 +1272,7 @@ command on the same database can have unpredictable results. | |||
1272 | The | 1272 | The |
1273 | .Ar copy_extensions | 1273 | .Ar copy_extensions |
1274 | option should be used with caution. | 1274 | option should be used with caution. |
1275 | If care is not taken, then it can be a security risk. | 1275 | If care is not taken, it can be a security risk. |
1276 | For example, if a certificate request contains a | 1276 | For example, if a certificate request contains a |
1277 | .Em basicConstraints | 1277 | .Em basicConstraints |
1278 | extension with CA:TRUE and the | 1278 | extension with CA:TRUE and the |
@@ -1347,7 +1347,7 @@ this is when similar ciphers are available for | |||
1347 | SSL v2 and for SSL v3/TLS v1. | 1347 | SSL v2 and for SSL v3/TLS v1. |
1348 | .It Ar cipherlist | 1348 | .It Ar cipherlist |
1349 | A cipher list to convert to a cipher preference list. | 1349 | A cipher list to convert to a cipher preference list. |
1350 | If it is not included, then the default cipher list will be used. | 1350 | If it is not included, the default cipher list will be used. |
1351 | The format is described below. | 1351 | The format is described below. |
1352 | .El | 1352 | .El |
1353 | .Sh CIPHERS LIST FORMAT | 1353 | .Sh CIPHERS LIST FORMAT |
@@ -1405,7 +1405,7 @@ If | |||
1405 | is used, then the ciphers are moved to the end of the list. | 1405 | is used, then the ciphers are moved to the end of the list. |
1406 | This option doesn't add any new ciphers, it just moves matching existing ones. | 1406 | This option doesn't add any new ciphers, it just moves matching existing ones. |
1407 | .Pp | 1407 | .Pp |
1408 | If none of these characters is present, then the string is just interpreted | 1408 | If none of these characters is present, the string is just interpreted |
1409 | as a list of ciphers to be appended to the current preference list. | 1409 | as a list of ciphers to be appended to the current preference list. |
1410 | If the list includes any ciphers already present, they will be ignored; | 1410 | If the list includes any ciphers already present, they will be ignored; |
1411 | that is, they will not be moved to the end of the list. | 1411 | that is, they will not be moved to the end of the list. |
@@ -1701,7 +1701,7 @@ The options are as follows: | |||
1701 | .It Fl CAfile Ar file | 1701 | .It Fl CAfile Ar file |
1702 | Verify the signature on a CRL by looking up the issuing certificate in | 1702 | Verify the signature on a CRL by looking up the issuing certificate in |
1703 | .Ar file . | 1703 | .Ar file . |
1704 | .It Fl CApath Ar dir | 1704 | .It Fl CApath Ar directory |
1705 | Verify the signature on a CRL by looking up the issuing certificate in | 1705 | Verify the signature on a CRL by looking up the issuing certificate in |
1706 | .Ar dir . | 1706 | .Ar dir . |
1707 | This directory must be a standard certificate directory, | 1707 | This directory must be a standard certificate directory, |
@@ -1943,7 +1943,7 @@ If no files are specified then standard input is used. | |||
1943 | The digest of choice for all new applications is SHA1. | 1943 | The digest of choice for all new applications is SHA1. |
1944 | Other digests are, however, still widely used. | 1944 | Other digests are, however, still widely used. |
1945 | .Pp | 1945 | .Pp |
1946 | If you wish to sign or verify data using the DSA algorithm, then the dss1 | 1946 | If you wish to sign or verify data using the DSA algorithm, the dss1 |
1947 | digest must be used. | 1947 | digest must be used. |
1948 | .Pp | 1948 | .Pp |
1949 | A source of random numbers is required for certain signing algorithms, in | 1949 | A source of random numbers is required for certain signing algorithms, in |
@@ -1993,7 +1993,7 @@ The options are as follows: | |||
1993 | .It Fl 2 , 5 | 1993 | .It Fl 2 , 5 |
1994 | The generator to use, either 2 or 5. | 1994 | The generator to use, either 2 or 5. |
1995 | 2 is the default. | 1995 | 2 is the default. |
1996 | If present, then the input file is ignored and parameters are generated instead. | 1996 | If present, the input file is ignored and parameters are generated instead. |
1997 | .It Fl C | 1997 | .It Fl C |
1998 | This option converts the parameters into C code. | 1998 | This option converts the parameters into C code. |
1999 | The parameters can then be loaded by calling the | 1999 | The parameters can then be loaded by calling the |
@@ -2047,8 +2047,8 @@ This option inhibits the output of the encoded version of the parameters. | |||
2047 | This argument specifies that a parameter set should be generated of size | 2047 | This argument specifies that a parameter set should be generated of size |
2048 | .Ar numbits . | 2048 | .Ar numbits . |
2049 | It must be the last option. | 2049 | It must be the last option. |
2050 | If not present, then a value of 512 is used. | 2050 | If not present, a value of 512 is used. |
2051 | If this value is present, then the input file is ignored and | 2051 | If this value is present, the input file is ignored and |
2052 | parameters are generated instead. | 2052 | parameters are generated instead. |
2053 | .It Fl out Ar file | 2053 | .It Fl out Ar file |
2054 | This specifies the output | 2054 | This specifies the output |
@@ -2338,7 +2338,7 @@ This option inhibits the output of the encoded version of the parameters. | |||
2338 | .It Ar numbits | 2338 | .It Ar numbits |
2339 | This option specifies that a parameter set should be generated of size | 2339 | This option specifies that a parameter set should be generated of size |
2340 | .Ar numbits . | 2340 | .Ar numbits . |
2341 | If this option is included, then the input file | 2341 | If this option is included, the input file |
2342 | .Pq if any | 2342 | .Pq if any |
2343 | is ignored. | 2343 | is ignored. |
2344 | .It Fl out Ar file | 2344 | .It Fl out Ar file |
@@ -2411,7 +2411,7 @@ option is set, then base64 process the data on one line. | |||
2411 | Base64 process the data. | 2411 | Base64 process the data. |
2412 | This means that if encryption is taking place, the data is base64-encoded | 2412 | This means that if encryption is taking place, the data is base64-encoded |
2413 | after encryption. | 2413 | after encryption. |
2414 | If decryption is set, then the input data is base64 decoded before | 2414 | If decryption is set, the input data is base64 decoded before |
2415 | being decrypted. | 2415 | being decrypted. |
2416 | .It Fl bufsize Ar number | 2416 | .It Fl bufsize Ar number |
2417 | Set the buffer size for I/O. | 2417 | Set the buffer size for I/O. |
@@ -2597,7 +2597,7 @@ this allows a rudimentary integrity or password check to be performed. | |||
2597 | However, since the chance of random data passing the test is | 2597 | However, since the chance of random data passing the test is |
2598 | better than 1 in 256, it isn't a very good test. | 2598 | better than 1 in 256, it isn't a very good test. |
2599 | .Pp | 2599 | .Pp |
2600 | If padding is disabled, then the input data must be a multiple of the cipher | 2600 | If padding is disabled, the input data must be a multiple of the cipher |
2601 | block length. | 2601 | block length. |
2602 | .Pp | 2602 | .Pp |
2603 | All RC2 ciphers have the same key and effective key length. | 2603 | All RC2 ciphers have the same key and effective key length. |
@@ -2986,7 +2986,7 @@ and allowing multiple certificate files to be used. | |||
2986 | .Op Fl trust_other | 2986 | .Op Fl trust_other |
2987 | .Op Fl CA Ar file | 2987 | .Op Fl CA Ar file |
2988 | .Op Fl CAfile Ar file | 2988 | .Op Fl CAfile Ar file |
2989 | .Op Fl CApath Ar path | 2989 | .Op Fl CApath Ar directory |
2990 | .Op Fl cert Ar file | 2990 | .Op Fl cert Ar file |
2991 | .Oo | 2991 | .Oo |
2992 | .Fl host | 2992 | .Fl host |
@@ -3034,7 +3034,7 @@ and behave like a mini OCSP server itself. | |||
3034 | .Pp | 3034 | .Pp |
3035 | The options are as follows: | 3035 | The options are as follows: |
3036 | .Bl -tag -width "XXXX" | 3036 | .Bl -tag -width "XXXX" |
3037 | .It Fl CAfile Ar file , Fl CApath Ar path | 3037 | .It Fl CAfile Ar file , Fl CApath Ar directory |
3038 | .Ar file | 3038 | .Ar file |
3039 | or | 3039 | or |
3040 | .Ar path | 3040 | .Ar path |
@@ -3166,7 +3166,7 @@ If the | |||
3166 | .Fl signkey | 3166 | .Fl signkey |
3167 | option is not present, then the private key is read from the same file | 3167 | option is not present, then the private key is read from the same file |
3168 | as the certificate. | 3168 | as the certificate. |
3169 | If neither option is specified, then the OCSP request is not signed. | 3169 | If neither option is specified, the OCSP request is not signed. |
3170 | .It Fl trust_other | 3170 | .It Fl trust_other |
3171 | The certificates specified by the | 3171 | The certificates specified by the |
3172 | .Fl verify_certs | 3172 | .Fl verify_certs |
@@ -3269,7 +3269,7 @@ or | |||
3269 | when fresh revocation information is available: used in the | 3269 | when fresh revocation information is available: used in the |
3270 | .Ar nextUpdate | 3270 | .Ar nextUpdate |
3271 | field. | 3271 | field. |
3272 | If neither option is present, then the | 3272 | If neither option is present, the |
3273 | .Em nextUpdate | 3273 | .Em nextUpdate |
3274 | field is omitted, meaning fresh revocation information is immediately available. | 3274 | field is omitted, meaning fresh revocation information is immediately available. |
3275 | .It Fl nrequest Ar number | 3275 | .It Fl nrequest Ar number |
@@ -3314,7 +3314,7 @@ options or they will be looked for in the standard | |||
3314 | certificates | 3314 | certificates |
3315 | directory. | 3315 | directory. |
3316 | .Pp | 3316 | .Pp |
3317 | If the initial verify fails, then the OCSP verify process halts with an | 3317 | If the initial verify fails, the OCSP verify process halts with an |
3318 | error. | 3318 | error. |
3319 | .Pp | 3319 | .Pp |
3320 | Otherwise the issuing CA certificate in the request is compared to the OCSP | 3320 | Otherwise the issuing CA certificate in the request is compared to the OCSP |
@@ -3329,7 +3329,7 @@ Otherwise the root CA of the OCSP responder's CA is checked to see if it | |||
3329 | is trusted for OCSP signing. | 3329 | is trusted for OCSP signing. |
3330 | If it is, the OCSP verify succeeds. | 3330 | If it is, the OCSP verify succeeds. |
3331 | .Pp | 3331 | .Pp |
3332 | If none of these checks is successful, then the OCSP verify fails. | 3332 | If none of these checks is successful, the OCSP verify fails. |
3333 | .Pp | 3333 | .Pp |
3334 | What this effectively means is that if the OCSP responder certificate is | 3334 | What this effectively means is that if the OCSP responder certificate is |
3335 | authorised directly by the CA it is issuing revocation information about | 3335 | authorised directly by the CA it is issuing revocation information about |
@@ -3695,7 +3695,7 @@ contains a SEQUENCE consisting of the public and private keys, respectively. | |||
3695 | This specifies the output | 3695 | This specifies the output |
3696 | .Ar file | 3696 | .Ar file |
3697 | to write a key to, or standard output by default. | 3697 | to write a key to, or standard output by default. |
3698 | If any encryption options are set, then a pass phrase will be prompted for. | 3698 | If any encryption options are set, a pass phrase will be prompted for. |
3699 | The output filename should | 3699 | The output filename should |
3700 | .Em not | 3700 | .Em not |
3701 | be the same as the input filename. | 3701 | be the same as the input filename. |
@@ -3998,7 +3998,7 @@ See the list in the | |||
3998 | .Sx PKCS12 NOTES | 3998 | .Sx PKCS12 NOTES |
3999 | section for more information. | 3999 | section for more information. |
4000 | .It Fl chain | 4000 | .It Fl chain |
4001 | If this option is present, then an attempt is made to include the entire | 4001 | If this option is present, an attempt is made to include the entire |
4002 | certificate chain of the user certificate. | 4002 | certificate chain of the user certificate. |
4003 | The standard CA store is used for this search. | 4003 | The standard CA store is used for this search. |
4004 | If the search fails, it is considered a fatal error. | 4004 | If the search fails, it is considered a fatal error. |
@@ -4031,7 +4031,7 @@ If additional certificates are present, they will also be included | |||
4031 | in the PKCS#12 file. | 4031 | in the PKCS#12 file. |
4032 | .It Fl inkey Ar file | 4032 | .It Fl inkey Ar file |
4033 | File to read private key from. | 4033 | File to read private key from. |
4034 | If not present, then a private key must be present in the input file. | 4034 | If not present, a private key must be present in the input file. |
4035 | .It Fl keyex | keysig | 4035 | .It Fl keyex | keysig |
4036 | Specifies that the private key is to be used for key exchange or just signing. | 4036 | Specifies that the private key is to be used for key exchange or just signing. |
4037 | This option is only interpreted by MSIE and similar MS software. | 4037 | This option is only interpreted by MSIE and similar MS software. |
@@ -4131,7 +4131,7 @@ Using the | |||
4131 | .Fl clcerts | 4131 | .Fl clcerts |
4132 | option will solve this problem by only outputting the certificate | 4132 | option will solve this problem by only outputting the certificate |
4133 | corresponding to the private key. | 4133 | corresponding to the private key. |
4134 | If the CA certificates are required, then they can be output to a separate | 4134 | If the CA certificates are required, they can be output to a separate |
4135 | file using the | 4135 | file using the |
4136 | .Fl nokeys | 4136 | .Fl nokeys |
4137 | and | 4137 | and |
@@ -4420,7 +4420,7 @@ is the default. | |||
4420 | This gives the | 4420 | This gives the |
4421 | .Ar file | 4421 | .Ar file |
4422 | to write the newly created private key to. | 4422 | to write the newly created private key to. |
4423 | If this option is not specified, then the filename present in the | 4423 | If this option is not specified, the filename present in the |
4424 | configuration file is used. | 4424 | configuration file is used. |
4425 | .It Fl md2 | md4 | md5 | sha1 | 4425 | .It Fl md2 | md4 | md5 | sha1 |
4426 | This specifies the message digest to sign the request with. | 4426 | This specifies the message digest to sign the request with. |
@@ -4567,7 +4567,7 @@ They are currently ignored by | |||
4567 | request signing utilities, but some CAs might want them. | 4567 | request signing utilities, but some CAs might want them. |
4568 | .It Ar default_bits | 4568 | .It Ar default_bits |
4569 | This specifies the default key size in bits. | 4569 | This specifies the default key size in bits. |
4570 | If not specified, then 512 is used. | 4570 | If not specified, 512 is used. |
4571 | It is used if the | 4571 | It is used if the |
4572 | .Fl new | 4572 | .Fl new |
4573 | option is used. | 4573 | option is used. |
@@ -4586,7 +4586,7 @@ Possible values include | |||
4586 | .Ar md5 | 4586 | .Ar md5 |
4587 | and | 4587 | and |
4588 | .Ar sha1 . | 4588 | .Ar sha1 . |
4589 | If not present, then MD5 is used. | 4589 | If not present, MD5 is used. |
4590 | This option can be overridden on the command line. | 4590 | This option can be overridden on the command line. |
4591 | .It Ar distinguished_name | 4591 | .It Ar distinguished_name |
4592 | This specifies the section containing the distinguished name fields to | 4592 | This specifies the section containing the distinguished name fields to |
@@ -4742,8 +4742,8 @@ is the field name being used, for example | |||
4742 | The | 4742 | The |
4743 | .Qq prompt | 4743 | .Qq prompt |
4744 | string is used to ask the user to enter the relevant details. | 4744 | string is used to ask the user to enter the relevant details. |
4745 | If the user enters nothing, then the default value is used; | 4745 | If the user enters nothing, the default value is used; |
4746 | if no default value is present, then the field is omitted. | 4746 | if no default value is present, the field is omitted. |
4747 | A field can still be omitted if a default value is present, | 4747 | A field can still be omitted if a default value is present, |
4748 | if the user just enters the | 4748 | if the user just enters the |
4749 | .Sq \&. | 4749 | .Sq \&. |
@@ -5093,7 +5093,7 @@ This option prints out the value of the modulus of the key. | |||
5093 | This specifies the output | 5093 | This specifies the output |
5094 | .Ar file | 5094 | .Ar file |
5095 | to write a key to, or standard output if this option is not specified. | 5095 | to write a key to, or standard output if this option is not specified. |
5096 | If any encryption options are set, then a pass phrase will be prompted for. | 5096 | If any encryption options are set, a pass phrase will be prompted for. |
5097 | The output filename should | 5097 | The output filename should |
5098 | .Em not | 5098 | .Em not |
5099 | be the same as the input filename. | 5099 | be the same as the input filename. |
@@ -5347,7 +5347,7 @@ It can be extracted with: | |||
5347 | .Pp | 5347 | .Pp |
5348 | The certificate public key can be extracted with: | 5348 | The certificate public key can be extracted with: |
5349 | .Pp | 5349 | .Pp |
5350 | .Dl $ openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem | 5350 | .Dl $ openssl x509 -in test/testx509.pem -pubkey -noout \*(Gtpubkey.pem |
5351 | .Pp | 5351 | .Pp |
5352 | The signature can be analysed with: | 5352 | The signature can be analysed with: |
5353 | .Pp | 5353 | .Pp |
@@ -5472,7 +5472,7 @@ This specifies the | |||
5472 | and optional | 5472 | and optional |
5473 | .Ar port | 5473 | .Ar port |
5474 | to connect to. | 5474 | to connect to. |
5475 | If not specified, then an attempt is made to connect to the local host | 5475 | If not specified, an attempt is made to connect to the local host |
5476 | on port 4433. | 5476 | on port 4433. |
5477 | Alternatively, the host and port pair may be separated using a forward-slash | 5477 | Alternatively, the host and port pair may be separated using a forward-slash |
5478 | character. | 5478 | character. |
@@ -5495,7 +5495,7 @@ Inhibit shutting down the connection when end of file is reached in the | |||
5495 | input. | 5495 | input. |
5496 | .It Fl key Ar keyfile | 5496 | .It Fl key Ar keyfile |
5497 | The private key to use. | 5497 | The private key to use. |
5498 | If not specified, then the certificate file will be used. | 5498 | If not specified, the certificate file will be used. |
5499 | .It Fl msg | 5499 | .It Fl msg |
5500 | Show all protocol messages with hex dump. | 5500 | Show all protocol messages with hex dump. |
5501 | .It Fl nbio | 5501 | .It Fl nbio |
@@ -5572,7 +5572,7 @@ As a side effect the connection will never fail due to a server | |||
5572 | certificate verify failure. | 5572 | certificate verify failure. |
5573 | .El | 5573 | .El |
5574 | .Sh S_CLIENT CONNECTED COMMANDS | 5574 | .Sh S_CLIENT CONNECTED COMMANDS |
5575 | If a connection is established with an SSL server, then any data received | 5575 | If a connection is established with an SSL server, any data received |
5576 | from the server is displayed and any key presses will be sent to the | 5576 | from the server is displayed and any key presses will be sent to the |
5577 | server. | 5577 | server. |
5578 | When used interactively (which means neither | 5578 | When used interactively (which means neither |
@@ -5593,11 +5593,11 @@ To connect to an SSL HTTP server the command: | |||
5593 | .Pp | 5593 | .Pp |
5594 | would typically be used | 5594 | would typically be used |
5595 | .Pq HTTPS uses port 443 . | 5595 | .Pq HTTPS uses port 443 . |
5596 | If the connection succeeds, then an HTTP command can be given such as | 5596 | If the connection succeeds, an HTTP command can be given such as |
5597 | .Qq GET | 5597 | .Qq GET |
5598 | to retrieve a web page. | 5598 | to retrieve a web page. |
5599 | .Pp | 5599 | .Pp |
5600 | If the handshake fails, then there are several possible causes; if it is | 5600 | If the handshake fails, there are several possible causes; if it is |
5601 | nothing obvious like no client certificate, then the | 5601 | nothing obvious like no client certificate, then the |
5602 | .Fl bugs , ssl2 , ssl3 , tls1 , | 5602 | .Fl bugs , ssl2 , ssl3 , tls1 , |
5603 | .Fl no_ssl2 , no_ssl3 , | 5603 | .Fl no_ssl2 , no_ssl3 , |
@@ -5633,7 +5633,7 @@ a client certificate. | |||
5633 | Therefore merely including a client certificate | 5633 | Therefore merely including a client certificate |
5634 | on the command line is no guarantee that the certificate works. | 5634 | on the command line is no guarantee that the certificate works. |
5635 | .Pp | 5635 | .Pp |
5636 | If there are problems verifying a server certificate, then the | 5636 | If there are problems verifying a server certificate, the |
5637 | .Fl showcerts | 5637 | .Fl showcerts |
5638 | option can be used to show the whole chain. | 5638 | option can be used to show the whole chain. |
5639 | .Sh S_CLIENT BUGS | 5639 | .Sh S_CLIENT BUGS |
@@ -5732,7 +5732,7 @@ certificate and some require a certificate with a certain public key type: | |||
5732 | for example the DSS cipher suites require a certificate containing a DSS | 5732 | for example the DSS cipher suites require a certificate containing a DSS |
5733 | .Pq DSA | 5733 | .Pq DSA |
5734 | key. | 5734 | key. |
5735 | If not specified, then the file | 5735 | If not specified, the file |
5736 | .Pa server.pem | 5736 | .Pa server.pem |
5737 | will be used. | 5737 | will be used. |
5738 | .It Fl cipher Ar cipherlist | 5738 | .It Fl cipher Ar cipherlist |
@@ -5773,9 +5773,9 @@ Print extensive debugging information including a hex dump of all traffic. | |||
5773 | The DH parameter file to use. | 5773 | The DH parameter file to use. |
5774 | The ephemeral DH cipher suites generate keys | 5774 | The ephemeral DH cipher suites generate keys |
5775 | using a set of DH parameters. | 5775 | using a set of DH parameters. |
5776 | If not specified, then an attempt is made to | 5776 | If not specified, an attempt is made to |
5777 | load the parameters from the server certificate file. | 5777 | load the parameters from the server certificate file. |
5778 | If this fails, then a static set of parameters hard coded into the | 5778 | If this fails, a static set of parameters hard coded into the |
5779 | .Nm s_server | 5779 | .Nm s_server |
5780 | program will be used. | 5780 | program will be used. |
5781 | .It Fl engine Ar id | 5781 | .It Fl engine Ar id |
@@ -5811,7 +5811,7 @@ generating a unique range of session IDs | |||
5811 | .Pq e.g. with a certain prefix . | 5811 | .Pq e.g. with a certain prefix . |
5812 | .It Fl key Ar keyfile | 5812 | .It Fl key Ar keyfile |
5813 | The private key to use. | 5813 | The private key to use. |
5814 | If not specified, then the certificate file will be used. | 5814 | If not specified, the certificate file will be used. |
5815 | .It Fl msg | 5815 | .It Fl msg |
5816 | Show all protocol messages with hex dump. | 5816 | Show all protocol messages with hex dump. |
5817 | .It Fl nbio | 5817 | .It Fl nbio |
@@ -5819,7 +5819,7 @@ Turns on non-blocking I/O. | |||
5819 | .It Fl nbio_test | 5819 | .It Fl nbio_test |
5820 | Tests non-blocking I/O. | 5820 | Tests non-blocking I/O. |
5821 | .It Fl no_dhe | 5821 | .It Fl no_dhe |
5822 | If this option is set, then no DH parameters will be loaded, effectively | 5822 | If this option is set, no DH parameters will be loaded, effectively |
5823 | disabling the ephemeral DH cipher suites. | 5823 | disabling the ephemeral DH cipher suites. |
5824 | .It Xo | 5824 | .It Xo |
5825 | .Fl no_ssl2 | no_ssl3 | no_tls1 | | 5825 | .Fl no_ssl2 | no_ssl3 | no_tls1 | |
@@ -5832,7 +5832,7 @@ with all servers and permit them to use SSL v3, SSL v2, or TLS as appropriate. | |||
5832 | Certain export cipher suites sometimes use a temporary RSA key; this option | 5832 | Certain export cipher suites sometimes use a temporary RSA key; this option |
5833 | disables temporary RSA key generation. | 5833 | disables temporary RSA key generation. |
5834 | .It Fl nocert | 5834 | .It Fl nocert |
5835 | If this option is set, then no certificate is used. | 5835 | If this option is set, no certificate is used. |
5836 | This restricts the cipher suites available to the anonymous ones | 5836 | This restricts the cipher suites available to the anonymous ones |
5837 | .Pq currently just anonymous DH . | 5837 | .Pq currently just anonymous DH . |
5838 | .It Fl quiet | 5838 | .It Fl quiet |
@@ -5942,9 +5942,197 @@ unknown cipher suites a client says it supports. | |||
5942 | .\" S_TIME | 5942 | .\" S_TIME |
5943 | .\" | 5943 | .\" |
5944 | .Sh S_TIME | 5944 | .Sh S_TIME |
5945 | .Nm openssl s_time | ||
5946 | .Bk -words | ||
5947 | .Op Fl bugs | ||
5948 | .Op Fl nbio | ||
5949 | .Op Fl new | ||
5950 | .Op Fl reuse | ||
5951 | .Op Fl ssl2 | ||
5952 | .Op Fl ssl3 | ||
5953 | .Op Fl CAfile Ar file | ||
5954 | .Op Fl CApath Ar directory | ||
5955 | .Op Fl cert Ar file | ||
5956 | .Op Fl cipher Ar cipherlist | ||
5957 | .Op Fl connect Ar host : Ns Ar port | ||
5958 | .Op Fl key Ar keyfile | ||
5959 | .Op Fl time Ar seconds | ||
5960 | .Op Fl verify Ar depth | ||
5961 | .Op Fl www Ar page | ||
5962 | .Ek | ||
5963 | .Pp | ||
5945 | The | 5964 | The |
5965 | .Nm s_client | ||
5966 | command implements a generic SSL/TLS client which connects to a | ||
5967 | remote host using SSL/TLS. | ||
5968 | It can request a page from the server and includes | ||
5969 | the time to transfer the payload data in its timing measurements. | ||
5970 | It measures the number of connections within a given timeframe, | ||
5971 | the amount of data transferred | ||
5972 | .Pq if any , | ||
5973 | and calculates the average time spent for one connection. | ||
5974 | .Pp | ||
5975 | The options are as follows: | ||
5976 | .Bl -tag -width Ds | ||
5977 | .It Fl bugs | ||
5978 | There are several known bugs in SSL and TLS implementations. | ||
5979 | Adding this option enables various workarounds. | ||
5980 | .It Fl CAfile Ar file | ||
5981 | A file containing trusted certificates to use during server authentication | ||
5982 | and to use when attempting to build the client certificate chain. | ||
5983 | .It Fl CApath Ar directory | ||
5984 | The directory to use for server certificate verification. | ||
5985 | This directory must be in | ||
5986 | .Qq hash format ; | ||
5987 | see | ||
5988 | .Nm verify | ||
5989 | for more information. | ||
5990 | These are also used when building the client certificate chain. | ||
5991 | .It Fl cert Ar file | ||
5992 | The certificate to use, if one is requested by the server. | ||
5993 | The default is not to use a certificate. | ||
5994 | The file is in PEM format. | ||
5995 | .It Fl cipher Ar cipherlist | ||
5996 | This allows the cipher list sent by the client to be modified. | ||
5997 | Although the server determines which cipher suite is used, | ||
5998 | it should take the first supported cipher in the list sent by the client. | ||
5999 | See the | ||
6000 | .Nm ciphers | ||
6001 | command for more information. | ||
6002 | .It Fl connect Ar host : Ns Ar port | ||
6003 | This specifies the host and optional port to connect to. | ||
6004 | .It Fl key Ar keyfile | ||
6005 | The private key to use. | ||
6006 | If not specified, the certificate file will be used. | ||
6007 | The file is in PEM format. | ||
6008 | .It Fl nbio | ||
6009 | Turns on non-blocking I/O. | ||
6010 | .It Fl new | ||
6011 | Performs the timing test using a new session ID for each connection. | ||
6012 | If neither | ||
6013 | .Fl new | ||
6014 | nor | ||
6015 | .Fl reuse | ||
6016 | are specified, | ||
6017 | they are both on by default and executed in sequence. | ||
6018 | .It Fl reuse | ||
6019 | Performs the timing test using the same session ID; | ||
6020 | this can be used as a test that session caching is working. | ||
6021 | If neither | ||
6022 | .Fl new | ||
6023 | nor | ||
6024 | .Fl reuse | ||
6025 | are specified, | ||
6026 | they are both on by default and executed in sequence. | ||
6027 | .It Fl ssl2 | ssl3 | ||
6028 | These options disable the use of certain SSL or TLS protocols. | ||
6029 | By default, the initial handshake uses a method | ||
6030 | which should be compatible with all servers and permit them to use | ||
6031 | SSL v3, SSL v2, or TLS as appropriate. | ||
6032 | The timing program is not as rich in options to turn protocols on and off as | ||
6033 | the | ||
6034 | .Nm s_client | ||
6035 | program and may not connect to all servers. | ||
6036 | .Pp | ||
6037 | Unfortunately there are a lot of ancient and broken servers in use which | ||
6038 | cannot handle this technique and will fail to connect. | ||
6039 | Some servers only work if TLS is turned off with the | ||
6040 | .Fl ssl3 | ||
6041 | option; | ||
6042 | others will only support SSL v2 and may need the | ||
6043 | .Fl ssl2 | ||
6044 | option. | ||
6045 | .It Fl time Ar seconds | ||
6046 | Specifies how long | ||
6047 | .Pq in seconds | ||
6048 | .Nm s_time | ||
6049 | should establish connections and | ||
6050 | optionally transfer payload data from a server. | ||
6051 | The default is 30 seconds. | ||
6052 | Server and client performance and the link speed | ||
6053 | determine how many connections | ||
6054 | .Nm s_time | ||
6055 | can establish. | ||
6056 | .It Fl verify Ar depth | ||
6057 | The verify depth to use. | ||
6058 | This specifies the maximum length of the server certificate chain | ||
6059 | and turns on server certificate verification. | ||
6060 | Currently the verify operation continues after errors, so all the problems | ||
6061 | with a certificate chain can be seen. | ||
6062 | As a side effect, | ||
6063 | the connection will never fail due to a server certificate verify failure. | ||
6064 | .It Fl www Ar page | ||
6065 | This specifies the page to GET from the server. | ||
6066 | A value of | ||
6067 | .Sq / | ||
6068 | gets the index.htm[l] page. | ||
6069 | If this parameter is not specified, | ||
5946 | .Nm s_time | 6070 | .Nm s_time |
5947 | utility is currently undocumented. | 6071 | will only perform the handshake to establish SSL connections |
6072 | but not transfer any payload data. | ||
6073 | .El | ||
6074 | .Sh S_TIME NOTES | ||
6075 | .Nm s_client | ||
6076 | can be used to measure the performance of an SSL connection. | ||
6077 | To connect to an SSL HTTP server and get the default page the command | ||
6078 | .Bd -literal -offset indent | ||
6079 | $ openssl s_time -connect servername:443 -www / -CApath yourdir \e | ||
6080 | -CAfile yourfile.pem -cipher commoncipher [-ssl3] | ||
6081 | .Ed | ||
6082 | .Pp | ||
6083 | would typically be used | ||
6084 | .Pq HTTPS uses port 443 . | ||
6085 | .Dq commoncipher | ||
6086 | is a cipher to which both client and server can agree; | ||
6087 | see the | ||
6088 | .Nm ciphers | ||
6089 | command for details. | ||
6090 | .Pp | ||
6091 | If the handshake fails, there are several possible causes: | ||
6092 | if it is nothing obvious like no client certificate, the | ||
6093 | .Fl bugs , ssl2 , | ||
6094 | and | ||
6095 | .Fl ssl3 | ||
6096 | options can be tried in case it is a buggy server. | ||
6097 | In particular you should play with these options | ||
6098 | .Em before | ||
6099 | submitting a bug report to an OpenSSL mailing list. | ||
6100 | .Pp | ||
6101 | A frequent problem when attempting to get client certificates working | ||
6102 | is that a web client complains it has no certificates or gives an empty | ||
6103 | list to choose from. | ||
6104 | This is normally because the server is not sending | ||
6105 | the clients certificate authority in its | ||
6106 | .Qq acceptable CA list | ||
6107 | when it requests a certificate. | ||
6108 | By using | ||
6109 | .Nm s_client , | ||
6110 | the CA list can be viewed and checked. | ||
6111 | However some servers only request client authentication | ||
6112 | after a specific URL is requested. | ||
6113 | To obtain the list in this case, it is necessary to use the | ||
6114 | .Fl prexit | ||
6115 | option of | ||
6116 | .Nm s_client | ||
6117 | and send an HTTP request for an appropriate page. | ||
6118 | .Pp | ||
6119 | If a certificate is specified on the command line using the | ||
6120 | .Fl cert | ||
6121 | option, | ||
6122 | it will not be used unless the server specifically requests | ||
6123 | a client certificate. | ||
6124 | Therefore merely including a client certificate | ||
6125 | on the command line is no guarantee that the certificate works. | ||
6126 | .Sh S_TIME BUGS | ||
6127 | Because this program does not have all the options of the | ||
6128 | .Nm s_client | ||
6129 | program to turn protocols on and off, | ||
6130 | you may not be able to measure the performance | ||
6131 | of all protocols with all servers. | ||
6132 | .Pp | ||
6133 | The | ||
6134 | .Fl verify | ||
6135 | option should really exit if the server verification fails. | ||
5948 | .\" | 6136 | .\" |
5949 | .\" SESS_ID | 6137 | .\" SESS_ID |
5950 | .\" | 6138 | .\" |
@@ -6229,7 +6417,7 @@ A | |||
6229 | .Ar file | 6417 | .Ar file |
6230 | containing trusted CA certificates; only used with | 6418 | containing trusted CA certificates; only used with |
6231 | .Fl verify . | 6419 | .Fl verify . |
6232 | .It Fl CApath Ar dir | 6420 | .It Fl CApath Ar directory |
6233 | A | 6421 | A |
6234 | .Ar directory | 6422 | .Ar directory |
6235 | containing trusted CA certificates; only used with | 6423 | containing trusted CA certificates; only used with |
@@ -6303,7 +6491,7 @@ When verifying these will be searched for the signers' certificates. | |||
6303 | The certificates should be in PEM format. | 6491 | The certificates should be in PEM format. |
6304 | .It Fl signer Ar file | 6492 | .It Fl signer Ar file |
6305 | The signer's certificate when signing a message. | 6493 | The signer's certificate when signing a message. |
6306 | If a message is being verified, then the signer's certificates will be | 6494 | If a message is being verified, the signer's certificates will be |
6307 | written to this file if the verification was successful. | 6495 | written to this file if the verification was successful. |
6308 | .It Fl recip Ar file | 6496 | .It Fl recip Ar file |
6309 | The recipients certificate when decrypting a message. | 6497 | The recipients certificate when decrypting a message. |
@@ -6312,7 +6500,7 @@ must match one of the recipients of the message or an error occurs. | |||
6312 | .It Fl inkey Ar file | 6500 | .It Fl inkey Ar file |
6313 | The private key to use when signing or decrypting. | 6501 | The private key to use when signing or decrypting. |
6314 | This must match the corresponding certificate. | 6502 | This must match the corresponding certificate. |
6315 | If this option is not specified, then the private key must be included | 6503 | If this option is not specified, the private key must be included |
6316 | in the certificate file specified with | 6504 | in the certificate file specified with |
6317 | the | 6505 | the |
6318 | .Fl recip | 6506 | .Fl recip |
@@ -6355,7 +6543,7 @@ a message. | |||
6355 | The relevant mail headers. | 6543 | The relevant mail headers. |
6356 | These are included outside the signed | 6544 | These are included outside the signed |
6357 | portion of a message so they may be included manually. | 6545 | portion of a message so they may be included manually. |
6358 | If signing, then many | 6546 | When signing, many |
6359 | .Em S/MIME | 6547 | .Em S/MIME |
6360 | mail clients check the signer's certificate email | 6548 | mail clients check the signer's certificate email |
6361 | address matches that specified in the From: address. | 6549 | address matches that specified in the From: address. |
@@ -6582,7 +6770,7 @@ The | |||
6582 | .Nm speed | 6770 | .Nm speed |
6583 | command is used to test the performance of cryptographic algorithms. | 6771 | command is used to test the performance of cryptographic algorithms. |
6584 | .Bl -tag -width "XXXX" | 6772 | .Bl -tag -width "XXXX" |
6585 | .It Cm [zero or more test algorithms] | 6773 | .It Bq Cm zero or more test algorithms |
6586 | If any options are given, | 6774 | If any options are given, |
6587 | .Nm speed | 6775 | .Nm speed |
6588 | tests those algorithms, otherwise all of the above are tested. | 6776 | tests those algorithms, otherwise all of the above are tested. |
@@ -6829,7 +7017,7 @@ This is useful if the first certificate filename begins with a | |||
6829 | One or more | 7017 | One or more |
6830 | .Ar certificates | 7018 | .Ar certificates |
6831 | to verify. | 7019 | to verify. |
6832 | If no certificate files are included, then an attempt is made to read | 7020 | If no certificate files are included, an attempt is made to read |
6833 | a certificate from standard input. | 7021 | a certificate from standard input. |
6834 | They should all be in PEM format. | 7022 | They should all be in PEM format. |
6835 | .El | 7023 | .El |
@@ -6915,7 +7103,7 @@ and | |||
6915 | dates in the certificate. | 7103 | dates in the certificate. |
6916 | The certificate signatures are also checked at this point. | 7104 | The certificate signatures are also checked at this point. |
6917 | .Pp | 7105 | .Pp |
6918 | If all operations complete successfully, then the certificate is considered | 7106 | If all operations complete successfully, the certificate is considered |
6919 | valid. | 7107 | valid. |
6920 | If any operation fails then the certificate is not valid. | 7108 | If any operation fails then the certificate is not valid. |
6921 | .Sh VERIFY DIAGNOSTICS | 7109 | .Sh VERIFY DIAGNOSTICS |
@@ -7072,7 +7260,7 @@ name must either appear in a file (as specified by the | |||
7072 | .Fl CAfile | 7260 | .Fl CAfile |
7073 | option) or a directory (as specified by | 7261 | option) or a directory (as specified by |
7074 | .Fl CApath ) . | 7262 | .Fl CApath ) . |
7075 | If they occur in both, then only the certificates in the file will | 7263 | If they occur in both, only the certificates in the file will |
7076 | be recognised. | 7264 | be recognised. |
7077 | .Pp | 7265 | .Pp |
7078 | Previous versions of | 7266 | Previous versions of |
@@ -7232,8 +7420,8 @@ such as the | |||
7232 | and | 7420 | and |
7233 | .Fl CA | 7421 | .Fl CA |
7234 | options. | 7422 | options. |
7235 | If not specified, then MD5 is used. | 7423 | If not specified, MD5 is used. |
7236 | If the key being used to sign with is a DSA key, then | 7424 | If the key being used to sign with is a DSA key, |
7237 | this option has no effect: SHA1 is always used with DSA keys. | 7425 | this option has no effect: SHA1 is always used with DSA keys. |
7238 | .It Fl engine Ar id | 7426 | .It Fl engine Ar id |
7239 | Specifying an engine (by it's unique | 7427 | Specifying an engine (by it's unique |
@@ -7427,7 +7615,7 @@ Any certificate extensions are retained unless the | |||
7427 | .Fl clrext | 7615 | .Fl clrext |
7428 | option is supplied. | 7616 | option is supplied. |
7429 | .Pp | 7617 | .Pp |
7430 | If the input is a certificate request, then a self-signed certificate | 7618 | If the input is a certificate request, a self-signed certificate |
7431 | is created using the supplied private key using the subject name in | 7619 | is created using the supplied private key using the subject name in |
7432 | the request. | 7620 | the request. |
7433 | .It Fl clrext | 7621 | .It Fl clrext |
@@ -7498,7 +7686,7 @@ Without the | |||
7498 | option, the input is a certificate which must be self-signed. | 7686 | option, the input is a certificate which must be self-signed. |
7499 | .It Fl CAkey Ar file | 7687 | .It Fl CAkey Ar file |
7500 | Sets the CA private key to sign a certificate with. | 7688 | Sets the CA private key to sign a certificate with. |
7501 | If this option is not specified, then it is assumed that the CA private key | 7689 | If this option is not specified, it is assumed that the CA private key |
7502 | is present in the CA certificate file. | 7690 | is present in the CA certificate file. |
7503 | .It Fl CAserial Ar file | 7691 | .It Fl CAserial Ar file |
7504 | Sets the CA serial number file to use. | 7692 | Sets the CA serial number file to use. |
@@ -7531,10 +7719,10 @@ Normally, if the | |||
7531 | option is specified and the serial number file does not exist, it is an error. | 7719 | option is specified and the serial number file does not exist, it is an error. |
7532 | .It Fl extfile Ar file | 7720 | .It Fl extfile Ar file |
7533 | File containing certificate extensions to use. | 7721 | File containing certificate extensions to use. |
7534 | If not specified, then no extensions are added to the certificate. | 7722 | If not specified, no extensions are added to the certificate. |
7535 | .It Fl extensions Ar section | 7723 | .It Fl extensions Ar section |
7536 | The section to add certificate extensions from. | 7724 | The section to add certificate extensions from. |
7537 | If this option is not specified, then the extensions should either be | 7725 | If this option is not specified, the extensions should either be |
7538 | contained in the unnamed | 7726 | contained in the unnamed |
7539 | .Pq default | 7727 | .Pq default |
7540 | section or the default section should contain a variable called | 7728 | section or the default section should contain a variable called |
@@ -7585,7 +7773,7 @@ and | |||
7585 | Escape the | 7773 | Escape the |
7586 | .Qq special | 7774 | .Qq special |
7587 | characters required by RFC 2253 in a field that is | 7775 | characters required by RFC 2253 in a field that is |
7588 | .Dq \& ,+"<>; . | 7776 | .Dq \& ,+"\*(Lt\*(Gt; . |
7589 | Additionally, | 7777 | Additionally, |
7590 | .Sq # | 7778 | .Sq # |
7591 | is escaped at the beginning of a string | 7779 | is escaped at the beginning of a string |
@@ -7612,15 +7800,15 @@ character. | |||
7612 | .It Ar utf8 | 7800 | .It Ar utf8 |
7613 | Convert all strings to UTF8 format first. | 7801 | Convert all strings to UTF8 format first. |
7614 | This is required by RFC 2253. | 7802 | This is required by RFC 2253. |
7615 | If you are lucky enough to have a UTF8 compatible terminal, then the use | 7803 | If you are lucky enough to have a UTF8 compatible terminal, |
7616 | of this option (and | 7804 | the use of this option (and |
7617 | .Em not | 7805 | .Em not |
7618 | setting | 7806 | setting |
7619 | .Ar esc_msb ) | 7807 | .Ar esc_msb ) |
7620 | may result in the correct display of multibyte | 7808 | may result in the correct display of multibyte |
7621 | .Pq international | 7809 | .Pq international |
7622 | characters. | 7810 | characters. |
7623 | If this option is not present, then multibyte characters larger than 0xff | 7811 | If this option is not present, multibyte characters larger than 0xff |
7624 | will be represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX | 7812 | will be represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX |
7625 | for 32 bits. | 7813 | for 32 bits. |
7626 | Also, if this option is off, any UTF8Strings will be converted to their | 7814 | Also, if this option is off, any UTF8Strings will be converted to their |
@@ -7645,7 +7833,7 @@ Both options use the RFC 2253 #XXXX... format. | |||
7645 | .It Ar dump_nostr | 7833 | .It Ar dump_nostr |
7646 | Dump non-character string types | 7834 | Dump non-character string types |
7647 | .Pq for example OCTET STRING ; | 7835 | .Pq for example OCTET STRING ; |
7648 | if this option is not set, then non-character string types will be displayed | 7836 | if this option is not set, non-character string types will be displayed |
7649 | as though each content octet represents a single character. | 7837 | as though each content octet represents a single character. |
7650 | .It Ar dump_all | 7838 | .It Ar dump_all |
7651 | Dump all fields. | 7839 | Dump all fields. |
@@ -7881,8 +8069,8 @@ The | |||
7881 | .Em basicConstraints | 8069 | .Em basicConstraints |
7882 | extension CA flag is used to determine whether the | 8070 | extension CA flag is used to determine whether the |
7883 | certificate can be used as a CA. | 8071 | certificate can be used as a CA. |
7884 | If the CA flag is true, then it is a CA; | 8072 | If the CA flag is true, it is a CA; |
7885 | if the CA flag is false, then it is not a CA. | 8073 | if the CA flag is false, it is not a CA. |
7886 | .Em All | 8074 | .Em All |
7887 | CAs should have the CA flag set to true. | 8075 | CAs should have the CA flag set to true. |
7888 | .Pp | 8076 | .Pp |