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