diff options
Diffstat (limited to 'doc/invoke-gnutls-serv.texi')
| -rw-r--r-- | doc/invoke-gnutls-serv.texi | 440 |
1 files changed, 440 insertions, 0 deletions
diff --git a/doc/invoke-gnutls-serv.texi b/doc/invoke-gnutls-serv.texi new file mode 100644 index 0000000..f2b54bd --- /dev/null +++ b/doc/invoke-gnutls-serv.texi @@ -0,0 +1,440 @@ +@node gnutls-serv Invocation +@heading Invoking gnutls-serv +@pindex gnutls-serv + +Server program that listens to incoming TLS connections. + +@anchor{gnutls-serv usage} +@subheading gnutls-serv help/usage (@option{-?}) +@cindex gnutls-serv help + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +gnutls-serv - GnuTLS server +Usage: gnutls-serv [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... + +None: + + -d, --debug=num Enable debugging + - it must be in the range: + 0 to 9999 + --sni-hostname=str Server's hostname for server name extension + --sni-hostname-fatal Send fatal alert on sni-hostname mismatch + --alpn=str Specify ALPN protocol to be enabled by the server + --alpn-fatal Send fatal alert on non-matching ALPN name + --noticket Don't accept session tickets + --earlydata Accept early data + --maxearlydata=num The maximum early data size to accept + - it must be in the range: + 1 to 2147483648 + --nocookie Don't require cookie on DTLS sessions + -g, --generate Generate Diffie-Hellman parameters + -q, --quiet Suppress some messages + --nodb Do not use a resumption database + --http Act as an HTTP server + --echo Act as an Echo server + --crlf Do not replace CRLF by LF in Echo server mode + -u, --udp Use DTLS (datagram TLS) over UDP + --mtu=num Set MTU for datagram TLS + - it must be in the range: + 0 to 17000 + --srtp-profiles=str Offer SRTP profiles + -a, --disable-client-cert Do not request a client certificate + - prohibits the option 'require-client-cert' + -r, --require-client-cert Require a client certificate + --verify-client-cert If a client certificate is sent then verify it + --compress-cert=str Compress certificate + -b, --heartbeat Activate heartbeat support + --x509fmtder Use DER format for certificates to read from + --priority=str Priorities string + --dhparams=file DH params file to use + - file must pre-exist + --x509cafile=str Certificate file or PKCS #11 URL to use + --x509crlfile=file CRL file to use + - file must pre-exist + --x509keyfile=str X.509 key file or PKCS #11 URL to use + --x509certfile=str X.509 Certificate file or PKCS #11 URL to use + --rawpkkeyfile=str Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use + --rawpkfile=str Raw public-key file to use + - requires the option 'rawpkkeyfile' + --srppasswd=file SRP password file to use + - file must pre-exist + --srppasswdconf=file SRP password configuration file to use + - file must pre-exist + --pskpasswd=file PSK password file to use + - file must pre-exist + --pskhint=str PSK identity hint to use + --ocsp-response=str The OCSP response to send to client + --ignore-ocsp-response-errors Ignore any errors when setting the OCSP response + -p, --port=num The port to connect to + -l, --list Print a list of the supported algorithms and modes + --provider=file Specify the PKCS #11 provider library + - file must pre-exist + --keymatexport=str Label used for exporting keying material + --keymatexportsize=num Size of the exported keying material + --recordsize=num The maximum record size to advertise + - it must be in the range: + 0 to 16384 + --httpdata=file The data used as HTTP response + - file must pre-exist + +Version, usage and configuration options: + + -v, --version[=arg] output version information and exit + -h, --help display extended usage information and exit + -!, --more-help extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +Server program that listens to incoming TLS connections. + +Please send bug reports to: <bugs@@gnutls.org> + +@end example +@exampleindent 4 + +@subheading debug option (-d). +@anchor{gnutls-serv debug} + +This is the ``enable debugging'' option. +This option takes a ArgumentType.NUMBER argument. +Specifies the debug level. +@subheading sni-hostname option. +@anchor{gnutls-serv sni-hostname} + +This is the ``server's hostname for server name extension'' option. +This option takes a ArgumentType.STRING argument. +Server name of type host_name that the server will recognise as its own. If the server receives client hello with different name, it will send a warning-level unrecognized_name alert. +@subheading alpn option. +@anchor{gnutls-serv alpn} + +This is the ``specify alpn protocol to be enabled by the server'' option. +This option takes a ArgumentType.STRING argument. +Specify the (textual) ALPN protocol for the server to use. +@subheading require-client-cert option (-r). +@anchor{gnutls-serv require-client-cert} + +This is the ``require a client certificate'' option. +This option before 3.6.0 used to imply --verify-client-cert. +Since 3.6.0 it will no longer verify the certificate by default. +@subheading verify-client-cert option. +@anchor{gnutls-serv verify-client-cert} + +This is the ``if a client certificate is sent then verify it'' option. +Do not require, but if a client certificate is sent then verify it and close the connection if invalid. +@subheading compress-cert option. +@anchor{gnutls-serv compress-cert} + +This is the ``compress certificate'' option. +This option takes a ArgumentType.STRING argument. +This option sets a supported compression method for certificate compression. +@subheading heartbeat option (-b). +@anchor{gnutls-serv heartbeat} + +This is the ``activate heartbeat support'' option. +Regularly ping client via heartbeat extension messages +@subheading priority option. +@anchor{gnutls-serv priority} + +This is the ``priorities string'' option. +This option takes a ArgumentType.STRING argument. +TLS algorithms and protocols to enable. You can +use predefined sets of ciphersuites such as PERFORMANCE, +NORMAL, SECURE128, SECURE256. The default is NORMAL. + +Check the GnuTLS manual on section ``Priority strings'' for more +information on allowed keywords +@subheading x509keyfile option. +@anchor{gnutls-serv x509keyfile} + +This is the ``x.509 key file or pkcs #11 url to use'' option. +This option takes a ArgumentType.STRING argument. +Specify the private key file or URI to use; it must correspond to +the certificate specified in --x509certfile. Multiple keys and certificates +can be specified with this option and in that case each occurrence of keyfile +must be followed by the corresponding x509certfile or vice-versa. +@subheading x509certfile option. +@anchor{gnutls-serv x509certfile} + +This is the ``x.509 certificate file or pkcs #11 url to use'' option. +This option takes a ArgumentType.STRING argument. +Specify the certificate file or URI to use; it must correspond to +the key specified in --x509keyfile. Multiple keys and certificates +can be specified with this option and in that case each occurrence of keyfile +must be followed by the corresponding x509certfile or vice-versa. +@subheading x509dsakeyfile option. +@anchor{gnutls-serv x509dsakeyfile} + +This is an alias for the @code{x509keyfile} option, +@pxref{gnutls-serv x509keyfile, the x509keyfile option documentation}. + +@subheading x509dsacertfile option. +@anchor{gnutls-serv x509dsacertfile} + +This is an alias for the @code{x509certfile} option, +@pxref{gnutls-serv x509certfile, the x509certfile option documentation}. + +@subheading x509ecckeyfile option. +@anchor{gnutls-serv x509ecckeyfile} + +This is an alias for the @code{x509keyfile} option, +@pxref{gnutls-serv x509keyfile, the x509keyfile option documentation}. + +@subheading x509ecccertfile option. +@anchor{gnutls-serv x509ecccertfile} + +This is an alias for the @code{x509certfile} option, +@pxref{gnutls-serv x509certfile, the x509certfile option documentation}. + +@subheading rawpkkeyfile option. +@anchor{gnutls-serv rawpkkeyfile} + +This is the ``private key file (pkcs #8 or pkcs #12) or pkcs #11 url to use'' option. +This option takes a ArgumentType.STRING argument. +Specify the private key file or URI to use; it must correspond to +the raw public-key specified in --rawpkfile. Multiple key pairs +can be specified with this option and in that case each occurrence of keyfile +must be followed by the corresponding rawpkfile or vice-versa. + +In order to instruct the application to negotiate raw public keys one +must enable the respective certificate types via the priority strings (i.e. CTYPE-CLI-* +and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section ``Priority strings'' for more +information on how to set certificate types. +@subheading rawpkfile option. +@anchor{gnutls-serv rawpkfile} + +This is the ``raw public-key file to use'' option. +This option takes a ArgumentType.STRING argument. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must appear in combination with the following options: +rawpkkeyfile. +@end itemize + +Specify the raw public-key file to use; it must correspond to +the private key specified in --rawpkkeyfile. Multiple key pairs +can be specified with this option and in that case each occurrence of keyfile +must be followed by the corresponding rawpkfile or vice-versa. + +In order to instruct the application to negotiate raw public keys one +must enable the respective certificate types via the priority strings (i.e. CTYPE-CLI-* +and CTYPE-SRV-* flags). + +Check the GnuTLS manual on section ``Priority strings'' for more +information on how to set certificate types. +@subheading ocsp-response option. +@anchor{gnutls-serv ocsp-response} + +This is the ``the ocsp response to send to client'' option. +This option takes a ArgumentType.STRING argument. +If the client requested an OCSP response, return data from this file to the client. +@subheading ignore-ocsp-response-errors option. +@anchor{gnutls-serv ignore-ocsp-response-errors} + +This is the ``ignore any errors when setting the ocsp response'' option. +That option instructs gnutls to not attempt to match the provided OCSP responses with the certificates. +@subheading list option (-l). +@anchor{gnutls-serv list} + +This is the ``print a list of the supported algorithms and modes'' option. +Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown. +@subheading provider option. +@anchor{gnutls-serv provider} + +This is the ``specify the pkcs #11 provider library'' option. +This option takes a ArgumentType.FILE argument. +This will override the default options in /etc/gnutls/pkcs11.conf +@subheading version option (-v). +@anchor{gnutls-serv version} + +This is the ``output version information and exit'' option. +This option takes a ArgumentType.KEYWORD argument. +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +@subheading help option (-h). +@anchor{gnutls-serv help} + +This is the ``display extended usage information and exit'' option. +Display usage information and exit. +@subheading more-help option (-!). +@anchor{gnutls-serv more-help} + +This is the ``extended usage information passed thru pager'' option. +Pass the extended usage information through a pager. +@anchor{gnutls-serv exit status} +@subheading gnutls-serv exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@end table +@anchor{gnutls-serv See Also} +@subsubheading gnutls-serv See Also +gnutls-cli-debug(1), gnutls-cli(1) +@anchor{gnutls-serv Examples} +@subsubheading gnutls-serv Examples +Running your own TLS server based on GnuTLS can be useful when +debugging clients and/or GnuTLS itself. This section describes how to +use @code{gnutls-serv} as a simple HTTPS server. + +The most basic server can be started as: + +@example +gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH" +@end example + +It will only support anonymous ciphersuites, which many TLS clients +refuse to use. + +The next step is to add support for X.509. First we generate a CA: + +@example +$ certtool --generate-privkey > x509-ca-key.pem +$ echo 'cn = GnuTLS test CA' > ca.tmpl +$ echo 'ca' >> ca.tmpl +$ echo 'cert_signing_key' >> ca.tmpl +$ certtool --generate-self-signed --load-privkey x509-ca-key.pem \ + --template ca.tmpl --outfile x509-ca.pem +@end example + +Then generate a server certificate. Remember to change the dns_name +value to the name of your server host, or skip that command to avoid +the field. + +@example +$ certtool --generate-privkey > x509-server-key.pem +$ echo 'organization = GnuTLS test server' > server.tmpl +$ echo 'cn = test.gnutls.org' >> server.tmpl +$ echo 'tls_www_server' >> server.tmpl +$ echo 'encryption_key' >> server.tmpl +$ echo 'signing_key' >> server.tmpl +$ echo 'dns_name = test.gnutls.org' >> server.tmpl +$ certtool --generate-certificate --load-privkey x509-server-key.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server.pem +@end example + +For use in the client, you may want to generate a client certificate +as well. + +@example +$ certtool --generate-privkey > x509-client-key.pem +$ echo 'cn = GnuTLS test client' > client.tmpl +$ echo 'tls_www_client' >> client.tmpl +$ echo 'encryption_key' >> client.tmpl +$ echo 'signing_key' >> client.tmpl +$ certtool --generate-certificate --load-privkey x509-client-key.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template client.tmpl --outfile x509-client.pem +@end example + +To be able to import the client key/certificate into some +applications, you will need to convert them into a PKCS#12 structure. +This also encrypts the security sensitive key with a password. + +@example +$ certtool --to-p12 --load-ca-certificate x509-ca.pem \ + --load-privkey x509-client-key.pem --load-certificate x509-client.pem \ + --outder --outfile x509-client.p12 +@end example + +For icing, we'll create a proxy certificate for the client too. + +@example +$ certtool --generate-privkey > x509-proxy-key.pem +$ echo 'cn = GnuTLS test client proxy' > proxy.tmpl +$ certtool --generate-proxy --load-privkey x509-proxy-key.pem \ + --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \ + --load-certificate x509-client.pem --template proxy.tmpl \ + --outfile x509-proxy.pem +@end example + +Then start the server again: + +@example +$ gnutls-serv --http \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem +@end example + +Try connecting to the server using your web browser. Note that the +server listens to port 5556 by default. + +While you are at it, to allow connections using ECDSA, you can also +create a ECDSA key and certificate for the server. These credentials +will be used in the final example below. + +@example +$ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem +$ certtool --generate-certificate --load-privkey x509-server-key-ecc.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server-ecc.pem +@end example + + +The next step is to add support for SRP authentication. This requires +an SRP password file created with @code{srptool}. +To start the server with SRP support: + +@example +gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt +@end example + +Let's also start a server with support for PSK. This would require +a password file created with @code{psktool}. + +@example +gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \ + --pskpasswd psk-passwd.txt +@end example + +If you want a server with support for raw public-keys we can also add these +credentials. Note however that there is no identity information linked to these +keys as is the case with regular x509 certificates. Authentication must be done +via different means. Also we need to explicitly enable raw public-key certificates +via the priority strings. + +@example +gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem +@end example + + +Finally, we start the server with all the earlier parameters and you +get this command: + +@example +gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem \ + --x509keyfile x509-server-key-ecc.pem \ + --x509certfile x509-server-ecc.pem \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt \ + --pskpasswd psk-passwd.txt \ + --rawpkfile srv.rawpk.pem \ + --rawpkkeyfile srv.key.pem +@end example |