doc/invoke-gnutls-serv.texi

   1 @node gnutls-serv Invocation
   2 @section Invoking gnutls-serv
   3 @pindex gnutls-serv
   4 @cindex GnuTLS server
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-gnutls-serv.texi)
   9 #
  10 # It has been AutoGen-ed  September 30, 2012 at 04:41:49 PM by AutoGen 5.16
  11 # From the definitions    ../src/serv-args.def
  12 # and the template file   agtexi-cmd.tpl
  13 @end ignore
  14
  15
  16 Server program that listens to incoming TLS connections.
  17
  18 This section was generated by @strong{AutoGen},
  19 using the @code{agtexi-cmd} template and the option descriptions for the @code{gnutls-serv} program.
  20 This software is released under the GNU General Public License, version 3 or later.
  21
  22
  23 @anchor{gnutls-serv usage}
  24 @subheading gnutls-serv help/usage (-h)
  25 @cindex gnutls-serv help
  26
  27 This is the automatically generated usage text for gnutls-serv.
  28 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  29 the usage text by passing it through a pager program.
  30 @code{more-help} is disabled on platforms without a working
  31 @code{fork(2)} function.  The @code{PAGER} environment variable is
  32 used to select the program, defaulting to @file{more}.  Both will exit
  33 with a status code of 0.
  34
  35 @exampleindent 0
  36 @example
  37 gnutls-serv - GnuTLS server - Ver. @@VERSION@@
  38 USAGE:  gnutls-serv [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  39
  40    -d, --debug=num            Enable debugging.
  41                                 - It must be in the range:
  42                                   0 to 9999
  43        --noticket             Don't accept session tickets
  44    -g, --generate             Generate Diffie-Hellman and RSA-export parameters
  45    -q, --quiet                Suppress some messages
  46        --nodb                 Do not use a resumption database
  47        --http                 Act as an HTTP server
  48        --echo                 Act as an Echo server
  49    -u, --udp                  Use DTLS (datagram TLS) over UDP
  50        --mtu=num              Set MTU for datagram TLS
  51                                 - It must be in the range:
  52                                   0 to 17000
  53    -a, --disable-client-cert  Do not request a client certificate
  54    -r, --require-client-cert  Require a client certificate
  55    -b, --heartbeat            Activate heartbeat support
  56        --x509fmtder           Use DER format for certificates to read from
  57        --priority=str         Priorities string
  58        --dhparams=file        DH params file to use
  59                                 - file must pre-exist
  60        --x509cafile=str       Certificate file or PKCS #11 URL to use
  61        --x509crlfile=file     CRL file to use
  62                                 - file must pre-exist
  63        --pgpkeyfile=file      PGP Key file to use
  64                                 - file must pre-exist
  65        --pgpkeyring=file      PGP Key ring file to use
  66                                 - file must pre-exist
  67        --pgpcertfile=file     PGP Public Key (certificate) file to use
  68                                 - file must pre-exist
  69        --x509keyfile=str      X.509 key file or PKCS #11 URL to use
  70        --x509certfile=str     X.509 Certificate file or PKCS #11 URL to use
  71        --x509dsakeyfile=str   Alternative X.509 key file or PKCS #11 URL to use
  72        --x509dsacertfile=str  Alternative X.509 Certificate file or PKCS #11 URL to use
  73        --x509ecckeyfile=str   Alternative X.509 key file or PKCS #11 URL to use
  74        --x509ecccertfile=str  Alternative X.509 Certificate file or PKCS #11 URL to use
  75        --pgpsubkey=str        PGP subkey to use (hex or auto)
  76        --srppasswd=file       SRP password file to use
  77                                 - file must pre-exist
  78        --srppasswdconf=file   SRP password configuration file to use
  79                                 - file must pre-exist
  80        --pskpasswd=file       PSK password file to use
  81                                 - file must pre-exist
  82        --pskhint=str          PSK identity hint to use
  83        --ocsp-response=file   The OCSP response to send to client
  84                                 - file must pre-exist
  85    -p, --port=num             The port to connect to
  86    -l, --list                 Print a list of the supported algorithms and modes
  87    -v, --version[=arg]        Output version information and exit
  88    -h, --help                 Display extended usage information and exit
  89    -!, --more-help            Extended usage information passed thru pager
  90
  91 Options are specified by doubled hyphens and their name or by a single
  92 hyphen and the flag character.
  93
  94
  95
  96 Server program that listens to incoming TLS connections.
  97
  98 please send bug reports to:  bug-gnutls@@gnu.org
  99 @end example
 100 @exampleindent 4
 101
 102 @anchor{gnutls-serv debug}
 103 @subheading debug option (-d)
 104 @cindex gnutls-serv-debug
 105
 106 This is the ``enable debugging.'' option.
 107 This option takes an argument number.
 108 Specifies the debug level.
 109 @anchor{gnutls-serv heartbeat}
 110 @subheading heartbeat option (-b)
 111 @cindex gnutls-serv-heartbeat
 112
 113 This is the ``activate heartbeat support'' option.
 114 Regularly ping client via heartbeat extension messages
 115 @anchor{gnutls-serv priority}
 116 @subheading priority option
 117 @cindex gnutls-serv-priority
 118
 119 This is the ``priorities string'' option.
 120 This option takes an argument string.
 121 TLS algorithms and protocols to enable. You can
 122 use predefined sets of ciphersuites such as PERFORMANCE,
 123 NORMAL, SECURE128, SECURE256.
 124
 125 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
 126 information on allowed keywords
 127 @anchor{gnutls-serv ocsp-response}
 128 @subheading ocsp-response option
 129 @cindex gnutls-serv-ocsp-response
 130
 131 This is the ``the ocsp response to send to client'' option.
 132 This option takes an argument file.
 133 If the client requested an OCSP response, return data from this file to the client.
 134 @anchor{gnutls-serv list}
 135 @subheading list option (-l)
 136 @cindex gnutls-serv-list
 137
 138 This is the ``print a list of the supported algorithms and modes'' option.
 139 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
 140 @anchor{gnutls-serv exit status}
 141 @subheading gnutls-serv exit status
 142
 143 One of the following exit values will be returned:
 144 @table @samp
 145 @item 0 (EXIT_SUCCESS)
 146 Successful program execution.
 147 @item 1 (EXIT_FAILURE)
 148 The operation failed or the command syntax was not valid.
 149 @end table
 150 @anchor{gnutls-serv See Also}
 151 @subheading gnutls-serv See Also
 152 gnutls-cli-debug(1), gnutls-cli(1)
 153
 154 @anchor{gnutls-serv Examples}
 155 @subheading gnutls-serv Examples
 156 Running your own TLS server based on GnuTLS can be useful when
 157 debugging clients and/or GnuTLS itself.  This section describes how to
 158 use @code{gnutls-serv} as a simple HTTPS server.
 159
 160 The most basic server can be started as:
 161
 162 @example
 163 gnutls-serv --http
 164 @end example
 165
 166 It will only support anonymous ciphersuites, which many TLS clients
 167 refuse to use.
 168
 169 The next step is to add support for X.509.  First we generate a CA:
 170
 171 @example
 172 $ certtool --generate-privkey > x509-ca-key.pem
 173 $ echo 'cn = GnuTLS test CA' > ca.tmpl
 174 $ echo 'ca' >> ca.tmpl
 175 $ echo 'cert_signing_key' >> ca.tmpl
 176 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
 177   --template ca.tmpl --outfile x509-ca.pem
 178 ...
 179 @end example
 180
 181 Then generate a server certificate.  Remember to change the dns_name
 182 value to the name of your server host, or skip that command to avoid
 183 the field.
 184
 185 @example
 186 $ certtool --generate-privkey > x509-server-key.pem
 187 $ echo 'organization = GnuTLS test server' > server.tmpl
 188 $ echo 'cn = test.gnutls.org' >> server.tmpl
 189 $ echo 'tls_www_server' >> server.tmpl
 190 $ echo 'encryption_key' >> server.tmpl
 191 $ echo 'signing_key' >> server.tmpl
 192 $ echo 'dns_name = test.gnutls.org' >> server.tmpl
 193 $ certtool --generate-certificate --load-privkey x509-server-key.pem \
 194   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 195   --template server.tmpl --outfile x509-server.pem
 196 ...
 197 @end example
 198
 199 For use in the client, you may want to generate a client certificate
 200 as well.
 201
 202 @example
 203 $ certtool --generate-privkey > x509-client-key.pem
 204 $ echo 'cn = GnuTLS test client' > client.tmpl
 205 $ echo 'tls_www_client' >> client.tmpl
 206 $ echo 'encryption_key' >> client.tmpl
 207 $ echo 'signing_key' >> client.tmpl
 208 $ certtool --generate-certificate --load-privkey x509-client-key.pem \
 209   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 210   --template client.tmpl --outfile x509-client.pem
 211 ...
 212 @end example
 213
 214 To be able to import the client key/certificate into some
 215 applications, you will need to convert them into a PKCS#12 structure.
 216 This also encrypts the security sensitive key with a password.
 217
 218 @example
 219 $ certtool --to-p12 --load-ca-certificate x509-ca.pem \
 220   --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
 221   --outder --outfile x509-client.p12
 222 @end example
 223
 224 For icing, we'll create a proxy certificate for the client too.
 225
 226 @example
 227 $ certtool --generate-privkey > x509-proxy-key.pem
 228 $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
 229 $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
 230   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
 231   --load-certificate x509-client.pem --template proxy.tmpl \
 232   --outfile x509-proxy.pem
 233 ...
 234 @end example
 235
 236 Then start the server again:
 237
 238 @example
 239 $ gnutls-serv --http \
 240             --x509cafile x509-ca.pem \
 241             --x509keyfile x509-server-key.pem \
 242             --x509certfile x509-server.pem
 243 @end example
 244
 245 Try connecting to the server using your web browser.  Note that the
 246 server listens to port 5556 by default.
 247
 248 While you are at it, to allow connections using DSA, you can also
 249 create a DSA key and certificate for the server.  These credentials
 250 will be used in the final example below.
 251
 252 @example
 253 $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem
 254 $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
 255   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 256   --template server.tmpl --outfile x509-server-dsa.pem
 257 ...
 258 @end example
 259
 260 The next step is to create OpenPGP credentials for the server.
 261
 262 @example
 263 gpg --gen-key
 264 ...enter whatever details you want, use 'test.gnutls.org' as name...
 265 @end example
 266
 267 Make a note of the OpenPGP key identifier of the newly generated key,
 268 here it was @code{5D1D14D8}.  You will need to export the key for
 269 GnuTLS to be able to use it.
 270
 271 @example
 272 gpg -a --export 5D1D14D8 > openpgp-server.txt
 273 gpg --export 5D1D14D8 > openpgp-server.bin
 274 gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
 275 gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
 276 @end example
 277
 278 Let's start the server with support for OpenPGP credentials:
 279
 280 @example
 281 gnutls-serv --http \
 282             --pgpkeyfile openpgp-server-key.txt \
 283             --pgpcertfile openpgp-server.txt
 284 @end example
 285
 286 The next step is to add support for SRP authentication. This requires
 287 an SRP password file created with @code{srptool}.
 288 To start the server with SRP support:
 289
 290 @example
 291 gnutls-serv --http \
 292             --srppasswdconf srp-tpasswd.conf \
 293             --srppasswd srp-passwd.txt
 294 @end example
 295
 296 Let's also start a server with support for PSK. This would require
 297 a password file created with @code{psktool}.
 298
 299 @example
 300 gnutls-serv --http \
 301             --pskpasswd psk-passwd.txt
 302 @end example
 303
 304 Finally, we start the server with all the earlier parameters and you
 305 get this command:
 306
 307 @example
 308 gnutls-serv --http \
 309             --x509cafile x509-ca.pem \
 310             --x509keyfile x509-server-key.pem \
 311             --x509certfile x509-server.pem \
 312             --x509dsakeyfile x509-server-key-dsa.pem \
 313             --x509dsacertfile x509-server-dsa.pem \
 314             --pgpkeyfile openpgp-server-key.txt \
 315             --pgpcertfile openpgp-server.txt \
 316             --srppasswdconf srp-tpasswd.conf \
 317             --srppasswd srp-passwd.txt \
 318             --pskpasswd psk-passwd.txt
 319 @end example
 320