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  November  8, 2012 at 11:40:16 PM by AutoGen 5.16
  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 (-h)
  24 @cindex gnutls-serv help
  25
  26 This is the automatically generated usage text for gnutls-serv.
  27 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!).  @code{more-help} will print
  28 the usage text by passing it through a pager program.
  29 @code{more-help} is disabled on platforms without a working
  30 @code{fork(2)} function.  The @code{PAGER} environment variable is
  31 used to select the program, defaulting to @file{more}.  Both will exit
  32 with a status code of 0.
  33
  34 @exampleindent 0
  35 @example
  36 gnutls-serv - GnuTLS server - Ver. @@VERSION@@
  37 USAGE:  gnutls-serv [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
  38
  39    -d, --debug=num            Enable debugging.
  40                                 - It must be in the range:
  41                                   0 to 9999
  42        --noticket             Don't accept session tickets
  43    -g, --generate             Generate Diffie-Hellman and RSA-export parameters
  44    -q, --quiet                Suppress some messages
  45        --nodb                 Do not use a resumption database
  46        --http                 Act as an HTTP server
  47        --echo                 Act as an Echo server
  48    -u, --udp                  Use DTLS (datagram TLS) over UDP
  49        --mtu=num              Set MTU for datagram TLS
  50                                 - It must be in the range:
  51                                   0 to 17000
  52        --srtp-profiles=str    Offer SRTP profiles
  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
 105 This is the ``enable debugging.'' option.
 106 This option takes an argument number.
 107 Specifies the debug level.
 108 @anchor{gnutls-serv heartbeat}
 109 @subheading heartbeat option (-b)
 110
 111 This is the ``activate heartbeat support'' option.
 112 Regularly ping client via heartbeat extension messages
 113 @anchor{gnutls-serv priority}
 114 @subheading priority option
 115
 116 This is the ``priorities string'' option.
 117 This option takes an argument string.
 118 TLS algorithms and protocols to enable. You can
 119 use predefined sets of ciphersuites such as PERFORMANCE,
 120 NORMAL, SECURE128, SECURE256.
 121
 122 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
 123 information on allowed keywords
 124 @anchor{gnutls-serv ocsp-response}
 125 @subheading ocsp-response option
 126
 127 This is the ``the ocsp response to send to client'' option.
 128 This option takes an argument file.
 129 If the client requested an OCSP response, return data from this file to the client.
 130 @anchor{gnutls-serv list}
 131 @subheading list option (-l)
 132
 133 This is the ``print a list of the supported algorithms and modes'' option.
 134 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
 135 @anchor{gnutls-serv exit status}
 136 @subheading gnutls-serv exit status
 137
 138 One of the following exit values will be returned:
 139 @table @samp
 140 @item 0 (EXIT_SUCCESS)
 141 Successful program execution.
 142 @item 1 (EXIT_FAILURE)
 143 The operation failed or the command syntax was not valid.
 144 @end table
 145 @anchor{gnutls-serv See Also}
 146 @subheading gnutls-serv See Also
 147 gnutls-cli-debug(1), gnutls-cli(1)
 148
 149 @anchor{gnutls-serv Examples}
 150 @subheading gnutls-serv Examples
 151 Running your own TLS server based on GnuTLS can be useful when
 152 debugging clients and/or GnuTLS itself.  This section describes how to
 153 use @code{gnutls-serv} as a simple HTTPS server.
 154
 155 The most basic server can be started as:
 156
 157 @example
 158 gnutls-serv --http
 159 @end example
 160
 161 It will only support anonymous ciphersuites, which many TLS clients
 162 refuse to use.
 163
 164 The next step is to add support for X.509.  First we generate a CA:
 165
 166 @example
 167 $ certtool --generate-privkey > x509-ca-key.pem
 168 $ echo 'cn = GnuTLS test CA' > ca.tmpl
 169 $ echo 'ca' >> ca.tmpl
 170 $ echo 'cert_signing_key' >> ca.tmpl
 171 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
 172   --template ca.tmpl --outfile x509-ca.pem
 173 ...
 174 @end example
 175
 176 Then generate a server certificate.  Remember to change the dns_name
 177 value to the name of your server host, or skip that command to avoid
 178 the field.
 179
 180 @example
 181 $ certtool --generate-privkey > x509-server-key.pem
 182 $ echo 'organization = GnuTLS test server' > server.tmpl
 183 $ echo 'cn = test.gnutls.org' >> server.tmpl
 184 $ echo 'tls_www_server' >> server.tmpl
 185 $ echo 'encryption_key' >> server.tmpl
 186 $ echo 'signing_key' >> server.tmpl
 187 $ echo 'dns_name = test.gnutls.org' >> server.tmpl
 188 $ certtool --generate-certificate --load-privkey x509-server-key.pem \
 189   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 190   --template server.tmpl --outfile x509-server.pem
 191 ...
 192 @end example
 193
 194 For use in the client, you may want to generate a client certificate
 195 as well.
 196
 197 @example
 198 $ certtool --generate-privkey > x509-client-key.pem
 199 $ echo 'cn = GnuTLS test client' > client.tmpl
 200 $ echo 'tls_www_client' >> client.tmpl
 201 $ echo 'encryption_key' >> client.tmpl
 202 $ echo 'signing_key' >> client.tmpl
 203 $ certtool --generate-certificate --load-privkey x509-client-key.pem \
 204   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 205   --template client.tmpl --outfile x509-client.pem
 206 ...
 207 @end example
 208
 209 To be able to import the client key/certificate into some
 210 applications, you will need to convert them into a PKCS#12 structure.
 211 This also encrypts the security sensitive key with a password.
 212
 213 @example
 214 $ certtool --to-p12 --load-ca-certificate x509-ca.pem \
 215   --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
 216   --outder --outfile x509-client.p12
 217 @end example
 218
 219 For icing, we'll create a proxy certificate for the client too.
 220
 221 @example
 222 $ certtool --generate-privkey > x509-proxy-key.pem
 223 $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
 224 $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
 225   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
 226   --load-certificate x509-client.pem --template proxy.tmpl \
 227   --outfile x509-proxy.pem
 228 ...
 229 @end example
 230
 231 Then start the server again:
 232
 233 @example
 234 $ gnutls-serv --http \
 235             --x509cafile x509-ca.pem \
 236             --x509keyfile x509-server-key.pem \
 237             --x509certfile x509-server.pem
 238 @end example
 239
 240 Try connecting to the server using your web browser.  Note that the
 241 server listens to port 5556 by default.
 242
 243 While you are at it, to allow connections using DSA, you can also
 244 create a DSA key and certificate for the server.  These credentials
 245 will be used in the final example below.
 246
 247 @example
 248 $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem
 249 $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
 250   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 251   --template server.tmpl --outfile x509-server-dsa.pem
 252 ...
 253 @end example
 254
 255 The next step is to create OpenPGP credentials for the server.
 256
 257 @example
 258 gpg --gen-key
 259 ...enter whatever details you want, use 'test.gnutls.org' as name...
 260 @end example
 261
 262 Make a note of the OpenPGP key identifier of the newly generated key,
 263 here it was @code{5D1D14D8}.  You will need to export the key for
 264 GnuTLS to be able to use it.
 265
 266 @example
 267 gpg -a --export 5D1D14D8 > openpgp-server.txt
 268 gpg --export 5D1D14D8 > openpgp-server.bin
 269 gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
 270 gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
 271 @end example
 272
 273 Let's start the server with support for OpenPGP credentials:
 274
 275 @example
 276 gnutls-serv --http \
 277             --pgpkeyfile openpgp-server-key.txt \
 278             --pgpcertfile openpgp-server.txt
 279 @end example
 280
 281 The next step is to add support for SRP authentication. This requires
 282 an SRP password file created with @code{srptool}.
 283 To start the server with SRP support:
 284
 285 @example
 286 gnutls-serv --http \
 287             --srppasswdconf srp-tpasswd.conf \
 288             --srppasswd srp-passwd.txt
 289 @end example
 290
 291 Let's also start a server with support for PSK. This would require
 292 a password file created with @code{psktool}.
 293
 294 @example
 295 gnutls-serv --http \
 296             --pskpasswd psk-passwd.txt
 297 @end example
 298
 299 Finally, we start the server with all the earlier parameters and you
 300 get this command:
 301
 302 @example
 303 gnutls-serv --http \
 304             --x509cafile x509-ca.pem \
 305             --x509keyfile x509-server-key.pem \
 306             --x509certfile x509-server.pem \
 307             --x509dsakeyfile x509-server-key-dsa.pem \
 308             --x509dsacertfile x509-server-dsa.pem \
 309             --pgpkeyfile openpgp-server-key.txt \
 310             --pgpcertfile openpgp-server.txt \
 311             --srppasswdconf srp-tpasswd.conf \
 312             --srppasswd srp-passwd.txt \
 313             --pskpasswd psk-passwd.txt
 314 @end example
 315