diff options
Diffstat (limited to 'doc/apps/s_server.pod.orig')
-rw-r--r-- | doc/apps/s_server.pod.orig | 523 |
1 files changed, 523 insertions, 0 deletions
diff --git a/doc/apps/s_server.pod.orig b/doc/apps/s_server.pod.orig new file mode 100644 index 0000000000..b9ef5e6864 --- /dev/null +++ b/doc/apps/s_server.pod.orig @@ -0,0 +1,523 @@ + +=pod + +=head1 NAME + +s_server - SSL/TLS server program + +=head1 SYNOPSIS + +B<openssl> B<s_server> +[B<-accept port>] +[B<-naccept count>] +[B<-context id>] +[B<-verify depth>] +[B<-Verify depth>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-cert filename>] +[B<-certform DER|PEM>] +[B<-key keyfile>] +[B<-keyform DER|PEM>] +[B<-pass arg>] +[B<-dcert filename>] +[B<-dcertform DER|PEM>] +[B<-dkey keyfile>] +[B<-dkeyform DER|PEM>] +[B<-dpass arg>] +[B<-dhparam filename>] +[B<-nbio>] +[B<-nbio_test>] +[B<-crlf>] +[B<-debug>] +[B<-msg>] +[B<-state>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-issuer_checks>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-verify_depth num>] +[B<-verify_return_error>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-nocert>] +[B<-cipher cipherlist>] +[B<-serverpref>] +[B<-quiet>] +[B<-ssl3>] +[B<-tls1>] +[B<-dtls>] +[B<-dtls1>] +[B<-dtls1_2>] +[B<-listen>] +[B<-async>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_dhe>] +[B<-bugs>] +[B<-comp>] +[B<-no_comp>] +[B<-brief>] +[B<-www>] +[B<-WWW>] +[B<-HTTP>] +[B<-engine id>] +[B<-tlsextdebug>] +[B<-no_ticket>] +[B<-id_prefix arg>] +[B<-rand file(s)>] +[B<-serverinfo file>] +[B<-no_resumption_on_reneg>] +[B<-status>] +[B<-status_verbose>] +[B<-status_timeout nsec>] +[B<-status_url url>] +[B<-nextprotoneg protocols>] + +=head1 DESCRIPTION + +The B<s_server> command implements a generic SSL/TLS server which listens +for connections on a given port using SSL/TLS. + +=head1 OPTIONS + +In addition to the options below the B<s_server> utility also supports the +common and server only options documented in the +L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)/SUPPORTED COMMAND LINE COMMANDS> manual +page. + +=over 4 + +=item B<-accept port> + +the TCP port to listen on for connections. If not specified 4433 is used. + +=item B<-naccept count> + +The server will exit after receiving B<number> connections, default unlimited. + +=item B<-context id> + +sets the SSL context id. It can be given any string value. If this option +is not present a default value will be used. + +=item B<-cert certname> + +The certificate to use, most servers cipher suites require the use of a +certificate and some require a certificate with a certain public key type: +for example the DSS cipher suites require a certificate containing a DSS +(DSA) key. If not specified then the filename "server.pem" will be used. + +=item B<-certform format> + +The certificate format to use: DER or PEM. PEM is the default. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-keyform format> + +The private format to use: DER or PEM. PEM is the default. + +=item B<-pass arg> + +the private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-dcert filename>, B<-dkey keyname> + +specify an additional certificate and private key, these behave in the +same manner as the B<-cert> and B<-key> options except there is no default +if they are not specified (no additional certificate and key is used). As +noted above some cipher suites require a certificate containing a key of +a certain type. Some cipher suites need a certificate carrying an RSA key +and some a DSS (DSA) key. By using RSA and DSS certificates and keys +a server can support clients which only support RSA or DSS cipher suites +by using an appropriate certificate. + +=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg> + +additional certificate and private key format and passphrase respectively. + +=item B<-nocert> + +if this option is set then no certificate is used. This restricts the +cipher suites available to the anonymous ones (currently just anonymous +DH). + +=item B<-dhparam filename> + +the DH parameter file to use. The ephemeral DH cipher suites generate keys +using a set of DH parameters. If not specified then an attempt is made to +load the parameters from the server certificate file. If this fails then +a static set of parameters hard coded into the s_server program will be used. + +=item B<-no_dhe> + +if this option is set then no DH parameters will be loaded effectively +disabling the ephemeral DH cipher suites. + +=item B<-crl_check>, B<-crl_check_all> + +Check the peer certificate has not been revoked by its CA. +The CRL(s) are appended to the certificate file. With the B<-crl_check_all> +option all CRLs of all CAs in the chain are checked. + +=item B<-CApath directory> + +The directory to use for client certificate verification. This directory +must be in "hash format", see B<verify> for more information. These are +also used when building the server certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during client authentication +and to use when attempting to build the server certificate chain. The list +is also used in the list of acceptable client CAs passed to the client when +a certificate is requested. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-verify depth>, B<-Verify depth> + +The verify depth to use. This specifies the maximum length of the +client certificate chain and makes the server request a certificate from +the client. With the B<-verify> option a certificate is requested but the +client does not have to send one, with the B<-Verify> option the client +must supply a certificate or an error occurs. + +If the ciphersuite cannot request a client certificate (for example an +anonymous ciphersuite or PSK) this option has no effect. + +=item B<-attime>, B<-check_ss_sig>, B<explicit_policy>, B<-extended_crl>, +B<-ignore_critical>, B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, +B<-partial_chain>, B<-policy>, B<-policy_check>, B<-policy_print>, B<-purpose>, +B<-suiteB_128>, B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, +B<-no_alt_chains>, B<-use_deltas>, B<-verify_depth>, B<-verify_email>, +B<-verify_hostname>, B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set different peer certificate verification options. +See the L<verify(1)> manual page for details. + +=item B<-verify_return_error> + +Verification errors normally just print a message but allow the +connection to continue, for debugging purposes. +If this option is used, then verification errors close the connection. + +=item B<-state> + +prints out the SSL session states. + +=item B<-debug> + +print extensive debugging information including a hex dump of all traffic. + +=item B<-msg> + +show all protocol messages with hex dump. + +=item B<-trace> + +show verbose trace output of protocol messages. OpenSSL needs to be compiled +with B<enable-ssl-trace> for this option to work. + +=item B<-msgfile> + +file to send output of B<-msg> or B<-trace> to, default standard output. + +=item B<-nbio_test> + +tests non blocking I/O + +=item B<-nbio> + +turns on non blocking I/O + +=item B<-crlf> + +this option translated a line feed from the terminal into CR+LF. + +=item B<-quiet> + +inhibit printing of session and certificate information. + +=item B<-psk_hint hint> + +Use the PSK identity hint B<hint> when using a PSK cipher suite. + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. + +=item B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> + +these options disable the use of certain SSL or TLS protocols. By default +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3 or TLS as appropriate. + +=item B<-dtls>, B<-dtls1>, B<-dtls1_2> + +these options make s_server use DTLS protocols instead of TLS. With B<-dtls> +s_server will negotiate any supported DTLS protcol version, whilst B<-dtls1> and +B<-dtls1_2> will only support DTLS1.0 and DTLS1.2 respectively. + +=item B<-listen> + +this option can only be used in conjunction with one of the DTLS options above. +With this option s_server will listen on a UDP port for incoming connections. +Any ClientHellos that arrive will be checked to see if they have a cookie in +them or not. Any without a cookie will be responded to with a +HelloVerifyRequest. If a ClientHello with a cookie is received then s_server +will connect to that peer and complete the handshake. + +=item B<-async> + +switch on asynchronous mode. Cryptographic operations will be performed +asynchronously. This will only have an effect if an asynchronous capable engine +is also used via the B<-engine> option. For test purposes the dummy async engine +(dasync) can be used (if available). + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-comp> + +Enable negotiation of TLS compression. +This option was introduced in OpenSSL 1.1.0. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-no_comp> + +Disable negotiation of TLS compression. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-brief> + +only provide a brief summary of connection parameters instead of the +normal verbose output. + +=item B<-cipher cipherlist> + +this allows the cipher list used by the server to be modified. When +the client sends a list of supported ciphers the first client cipher +also included in the server list is used. Because the client specifies +the preference order, the order of the server cipherlist irrelevant. See +the B<ciphers> command for more information. + +=item B<-serverpref> + +use the server's cipher preferences, rather than the client's preferences. + +=item B<-tlsextdebug> + +print out a hex dump of any TLS extensions received from the server. + +=item B<-no_ticket> + +disable RFC4507bis session ticket support. + +=item B<-www> + +sends a status message back to the client when it connects. This includes +lots of information about the ciphers used and various session parameters. +The output is in HTML format so this option will normally be used with a +web browser. + +=item B<-WWW> + +emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. + +=item B<-HTTP> + +emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. The files loaded are +assumed to contain a complete and correct HTTP response (lines that +are part of the HTTP response line and headers must end with CRLF). + +=item B<-rev> + +simple test server which just reverses the text received from the client +and sends it back to the server. Also sets B<-brief>. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<s_server> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-id_prefix arg> + +generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful +for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple +servers, when each of which might be generating a unique range of session +IDs (eg. with a certain prefix). + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by a OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-serverinfo file> + +a file containing one or more blocks of PEM data. Each PEM block +must encode a TLS ServerHello extension (2 bytes type, 2 bytes length, +followed by "length" bytes of extension data). If the client sends +an empty TLS ClientHello extension matching the type, the corresponding +ServerHello extension will be returned. + +=item B<-no_resumption_on_reneg> + +set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. + +=item B<-status> + +enables certificate status request support (aka OCSP stapling). + +=item B<-status_verbose> + +enables certificate status request support (aka OCSP stapling) and gives +a verbose printout of the OCSP response. + +=item B<-status_timeout nsec> + +sets the timeout for OCSP response to B<nsec> seconds. + +=item B<-status_url url> + +sets a fallback responder URL to use if no responder URL is present in the +server certificate. Without this option an error is returned if the server +certificate does not contain a responder address. + +=item B<-nextprotoneg protocols> + +enable Next Protocol Negotiation TLS extension and provide a +comma-separated list of supported protocol names. +The list should contain most wanted protocols first. +Protocol names are printable ASCII strings, for example "http/1.1" or +"spdy/3". + +=back + +=head1 CONNECTED COMMANDS + +If a connection request is established with an SSL client and neither the +B<-www> nor the B<-WWW> option has been used then normally any data received +from the client is displayed and any key presses will be sent to the client. + +Certain single letter commands are also recognized which perform special +operations: these are listed below. + +=over 4 + +=item B<q> + +end the current SSL connection but still accept new connections. + +=item B<Q> + +end the current SSL connection and exit. + +=item B<r> + +renegotiate the SSL session. + +=item B<R> + +renegotiate the SSL session and request a client certificate. + +=item B<P> + +send some plain text down the underlying TCP connection: this should +cause the client to disconnect due to a protocol violation. + +=item B<S> + +print out some session cache status information. + +=back + +=head1 NOTES + +B<s_server> can be used to debug SSL clients. To accept connections from +a web browser the command: + + openssl s_server -accept 443 -www + +can be used for example. + +Most web browsers (in particular Netscape and MSIE) only support RSA cipher +suites, so they cannot connect to servers which don't use a certificate +carrying an RSA key or a version of OpenSSL with RSA disabled. + +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL clients interpret this to +mean any CA is acceptable. This is useful for debugging purposes. + +The session parameters can printed out using the B<sess_id> program. + +=head1 BUGS + +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of s_server is rather +hard to read and not a model of how things should be done. A typical +SSL server program would be much simpler. + +The output of common ciphers is wrong: it just gives the list of ciphers that +OpenSSL recognizes and the client supports. + +There should be a way for the B<s_server> program to print out details of any +unknown cipher suites a client says it supports. + +=head1 SEE ALSO + +L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)> + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=cut |