doc/invoke-gnutls-serv.texi

   1 @node gnutls-serv Invocation
   2 @section Invoking gnutls-serv
   3 @pindex gnutls-serv
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-gnutls-serv.texi)
   8 #
   9 # It has been AutoGen-ed
  10 # From the definitions    ../src/serv-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Server program that listens to incoming TLS connections.
  16
  17 This section was generated by @strong{AutoGen},
  18 using the @code{agtexi-cmd} template and the option descriptions for the @code{gnutls-serv} program.
  19 This software is released under the GNU General Public License, version 3 or later.
  20
  21
  22 @anchor{gnutls-serv usage}
  23 @subheading gnutls-serv help/usage (@option{--help})
  24 @cindex gnutls-serv help
  25
  26 This is the automatically generated usage text for gnutls-serv.
  27
  28 The text printed is the same whether selected with the @code{help} option
  29 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  30 the usage text by passing it through a pager program.
  31 @code{more-help} is disabled on platforms without a working
  32 @code{fork(2)} function.  The @code{PAGER} environment variable is
  33 used to select the program, defaulting to @file{more}.  Both will exit
  34 with a status code of 0.
  35
  36 @exampleindent 0
  37 @example
  38 gnutls-serv is unavailable - no --help
  39 @end example
  40 @exampleindent 4
  41
  42 @anchor{gnutls-serv debug}
  43 @subheading debug option (-d)
  44
  45 This is the ``enable debugging'' option.
  46 This option takes a number argument.
  47 Specifies the debug level.
  48 @anchor{gnutls-serv verify-client-cert}
  49 @subheading verify-client-cert option
  50
  51 This is the ``if a client certificate is sent then verify it.'' option.
  52 Do not require, but if a client certificate is sent then verify it and close the connection if invalid.
  53 @anchor{gnutls-serv heartbeat}
  54 @subheading heartbeat option (-b)
  55
  56 This is the ``activate heartbeat support'' option.
  57 Regularly ping client via heartbeat extension messages
  58 @anchor{gnutls-serv priority}
  59 @subheading priority option
  60
  61 This is the ``priorities string'' option.
  62 This option takes a string argument.
  63 TLS algorithms and protocols to enable. You can
  64 use predefined sets of ciphersuites such as PERFORMANCE,
  65 NORMAL, SECURE128, SECURE256. The default is NORMAL.
  66
  67 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
  68 information on allowed keywords
  69 @anchor{gnutls-serv ocsp-response}
  70 @subheading ocsp-response option
  71
  72 This is the ``the ocsp response to send to client'' option.
  73 This option takes a file argument.
  74 If the client requested an OCSP response, return data from this file to the client.
  75 @anchor{gnutls-serv list}
  76 @subheading list option (-l)
  77
  78 This is the ``print a list of the supported algorithms and modes'' option.
  79 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
  80 @anchor{gnutls-serv provider}
  81 @subheading provider option
  82
  83 This is the ``specify the pkcs #11 provider library'' option.
  84 This option takes a file argument.
  85 This will override the default options in /etc/gnutls/pkcs11.conf
  86 @anchor{gnutls-serv exit status}
  87 @subheading gnutls-serv exit status
  88
  89 One of the following exit values will be returned:
  90 @table @samp
  91 @item 0 (EXIT_SUCCESS)
  92 Successful program execution.
  93 @item 1 (EXIT_FAILURE)
  94 The operation failed or the command syntax was not valid.
  95 @end table
  96 @anchor{gnutls-serv See Also}
  97 @subheading gnutls-serv See Also
  98 gnutls-cli-debug(1), gnutls-cli(1)
  99 @anchor{gnutls-serv Examples}
 100 @subheading gnutls-serv Examples
 101 Running your own TLS server based on GnuTLS can be useful when
 102 debugging clients and/or GnuTLS itself.  This section describes how to
 103 use @code{gnutls-serv} as a simple HTTPS server.
 104
 105 The most basic server can be started as:
 106
 107 @example
 108 gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH"
 109 @end example
 110
 111 It will only support anonymous ciphersuites, which many TLS clients
 112 refuse to use.
 113
 114 The next step is to add support for X.509.  First we generate a CA:
 115
 116 @example
 117 $ certtool --generate-privkey > x509-ca-key.pem
 118 $ echo 'cn = GnuTLS test CA' > ca.tmpl
 119 $ echo 'ca' >> ca.tmpl
 120 $ echo 'cert_signing_key' >> ca.tmpl
 121 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
 122   --template ca.tmpl --outfile x509-ca.pem
 123 ...
 124 @end example
 125
 126 Then generate a server certificate.  Remember to change the dns_name
 127 value to the name of your server host, or skip that command to avoid
 128 the field.
 129
 130 @example
 131 $ certtool --generate-privkey > x509-server-key.pem
 132 $ echo 'organization = GnuTLS test server' > server.tmpl
 133 $ echo 'cn = test.gnutls.org' >> server.tmpl
 134 $ echo 'tls_www_server' >> server.tmpl
 135 $ echo 'encryption_key' >> server.tmpl
 136 $ echo 'signing_key' >> server.tmpl
 137 $ echo 'dns_name = test.gnutls.org' >> server.tmpl
 138 $ certtool --generate-certificate --load-privkey x509-server-key.pem \
 139   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 140   --template server.tmpl --outfile x509-server.pem
 141 ...
 142 @end example
 143
 144 For use in the client, you may want to generate a client certificate
 145 as well.
 146
 147 @example
 148 $ certtool --generate-privkey > x509-client-key.pem
 149 $ echo 'cn = GnuTLS test client' > client.tmpl
 150 $ echo 'tls_www_client' >> client.tmpl
 151 $ echo 'encryption_key' >> client.tmpl
 152 $ echo 'signing_key' >> client.tmpl
 153 $ certtool --generate-certificate --load-privkey x509-client-key.pem \
 154   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 155   --template client.tmpl --outfile x509-client.pem
 156 ...
 157 @end example
 158
 159 To be able to import the client key/certificate into some
 160 applications, you will need to convert them into a PKCS#12 structure.
 161 This also encrypts the security sensitive key with a password.
 162
 163 @example
 164 $ certtool --to-p12 --load-ca-certificate x509-ca.pem \
 165   --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
 166   --outder --outfile x509-client.p12
 167 @end example
 168
 169 For icing, we'll create a proxy certificate for the client too.
 170
 171 @example
 172 $ certtool --generate-privkey > x509-proxy-key.pem
 173 $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
 174 $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
 175   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
 176   --load-certificate x509-client.pem --template proxy.tmpl \
 177   --outfile x509-proxy.pem
 178 ...
 179 @end example
 180
 181 Then start the server again:
 182
 183 @example
 184 $ gnutls-serv --http \
 185             --x509cafile x509-ca.pem \
 186             --x509keyfile x509-server-key.pem \
 187             --x509certfile x509-server.pem
 188 @end example
 189
 190 Try connecting to the server using your web browser.  Note that the
 191 server listens to port 5556 by default.
 192
 193 While you are at it, to allow connections using DSA, you can also
 194 create a DSA key and certificate for the server.  These credentials
 195 will be used in the final example below.
 196
 197 @example
 198 $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem
 199 $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
 200   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 201   --template server.tmpl --outfile x509-server-dsa.pem
 202 ...
 203 @end example
 204
 205 The next step is to create OpenPGP credentials for the server.
 206
 207 @example
 208 gpg --gen-key
 209 ...enter whatever details you want, use 'test.gnutls.org' as name...
 210 @end example
 211
 212 Make a note of the OpenPGP key identifier of the newly generated key,
 213 here it was @code{5D1D14D8}.  You will need to export the key for
 214 GnuTLS to be able to use it.
 215
 216 @example
 217 gpg -a --export 5D1D14D8 > openpgp-server.txt
 218 gpg --export 5D1D14D8 > openpgp-server.bin
 219 gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
 220 gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
 221 @end example
 222
 223 Let's start the server with support for OpenPGP credentials:
 224
 225 @example
 226 gnutls-serv --http --priority NORMAL:+CTYPE-OPENPGP \
 227             --pgpkeyfile openpgp-server-key.txt \
 228             --pgpcertfile openpgp-server.txt
 229 @end example
 230
 231 The next step is to add support for SRP authentication. This requires
 232 an SRP password file created with @code{srptool}.
 233 To start the server with SRP support:
 234
 235 @example
 236 gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP \
 237             --srppasswdconf srp-tpasswd.conf \
 238             --srppasswd srp-passwd.txt
 239 @end example
 240
 241 Let's also start a server with support for PSK. This would require
 242 a password file created with @code{psktool}.
 243
 244 @example
 245 gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK \
 246             --pskpasswd psk-passwd.txt
 247 @end example
 248
 249 Finally, we start the server with all the earlier parameters and you
 250 get this command:
 251
 252 @example
 253 gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-OPENPGP \
 254             --x509cafile x509-ca.pem \
 255             --x509keyfile x509-server-key.pem \
 256             --x509certfile x509-server.pem \
 257             --x509dsakeyfile x509-server-key-dsa.pem \
 258             --x509dsacertfile x509-server-dsa.pem \
 259             --pgpkeyfile openpgp-server-key.txt \
 260             --pgpcertfile openpgp-server.txt \
 261             --srppasswdconf srp-tpasswd.conf \
 262             --srppasswd srp-passwd.txt \
 263             --pskpasswd psk-passwd.txt
 264 @end example