Adding upstream version 3.7.9.upstream/3.7.9upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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