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  1, 2012 at 11:10:28 AM 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    -p, --port=num             The port to connect to
  84    -l, --list                 Print a list of the supported algorithms and modes
  85    -v, --version[=arg]        Output version information and exit
  86    -h, --help                 Display extended usage information and exit
  87    -!, --more-help            Extended usage information passed thru pager
  88
  89 Options are specified by doubled hyphens and their name or by a single
  90 hyphen and the flag character.
  91
  92
  93
  94 Server program that listens to incoming TLS connections.
  95
  96 please send bug reports to:  bug-gnutls@@gnu.org
  97 @end example
  98 @exampleindent 4
  99
 100 @anchor{gnutls-serv debug}
 101 @subheading debug option (-d)
 102 @cindex gnutls-serv-debug
 103
 104 This is the ``enable debugging.'' option.
 105 This option takes an argument number.
 106 Specifies the debug level.
 107 @anchor{gnutls-serv heartbeat}
 108 @subheading heartbeat option (-b)
 109 @cindex gnutls-serv-heartbeat
 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 @cindex gnutls-serv-priority
 116
 117 This is the ``priorities string'' option.
 118 This option takes an argument string.
 119 TLS algorithms and protocols to enable. You can
 120 use predefined sets of ciphersuites such as PERFORMANCE,
 121 NORMAL, SECURE128, SECURE256.
 122
 123 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
 124 information on allowed keywords
 125 @anchor{gnutls-serv list}
 126 @subheading list option (-l)
 127 @cindex gnutls-serv-list
 128
 129 This is the ``print a list of the supported algorithms and modes'' option.
 130 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
 131 @anchor{gnutls-serv exit status}
 132 @subheading gnutls-serv exit status
 133
 134 One of the following exit values will be returned:
 135 @table @samp
 136 @item 0 (EXIT_SUCCESS)
 137 Successful program execution.
 138 @item 1 (EXIT_FAILURE)
 139 The operation failed or the command syntax was not valid.
 140 @end table
 141 @anchor{gnutls-serv See Also}
 142 @subheading gnutls-serv See Also
 143 gnutls-cli-debug(1), gnutls-cli(1)
 144
 145 @anchor{gnutls-serv Examples}
 146 @subheading gnutls-serv Examples
 147 Running your own TLS server based on GnuTLS can be useful when
 148 debugging clients and/or GnuTLS itself.  This section describes how to
 149 use @code{gnutls-serv} as a simple HTTPS server.
 150
 151 The most basic server can be started as:
 152
 153 @example
 154 gnutls-serv --http
 155 @end example
 156
 157 It will only support anonymous ciphersuites, which many TLS clients
 158 refuse to use.
 159
 160 The next step is to add support for X.509.  First we generate a CA:
 161
 162 @example
 163 $ certtool --generate-privkey > x509-ca-key.pem
 164 $ echo 'cn = GnuTLS test CA' > ca.tmpl
 165 $ echo 'ca' >> ca.tmpl
 166 $ echo 'cert_signing_key' >> ca.tmpl
 167 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem \
 168   --template ca.tmpl --outfile x509-ca.pem
 169 ...
 170 @end example
 171
 172 Then generate a server certificate.  Remember to change the dns_name
 173 value to the name of your server host, or skip that command to avoid
 174 the field.
 175
 176 @example
 177 $ certtool --generate-privkey > x509-server-key.pem
 178 $ echo 'organization = GnuTLS test server' > server.tmpl
 179 $ echo 'cn = test.gnutls.org' >> server.tmpl
 180 $ echo 'tls_www_server' >> server.tmpl
 181 $ echo 'encryption_key' >> server.tmpl
 182 $ echo 'signing_key' >> server.tmpl
 183 $ echo 'dns_name = test.gnutls.org' >> server.tmpl
 184 $ certtool --generate-certificate --load-privkey x509-server-key.pem \
 185   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 186   --template server.tmpl --outfile x509-server.pem
 187 ...
 188 @end example
 189
 190 For use in the client, you may want to generate a client certificate
 191 as well.
 192
 193 @example
 194 $ certtool --generate-privkey > x509-client-key.pem
 195 $ echo 'cn = GnuTLS test client' > client.tmpl
 196 $ echo 'tls_www_client' >> client.tmpl
 197 $ echo 'encryption_key' >> client.tmpl
 198 $ echo 'signing_key' >> client.tmpl
 199 $ certtool --generate-certificate --load-privkey x509-client-key.pem \
 200   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 201   --template client.tmpl --outfile x509-client.pem
 202 ...
 203 @end example
 204
 205 To be able to import the client key/certificate into some
 206 applications, you will need to convert them into a PKCS#12 structure.
 207 This also encrypts the security sensitive key with a password.
 208
 209 @example
 210 $ certtool --to-p12 --load-ca-certificate x509-ca.pem \
 211   --load-privkey x509-client-key.pem --load-certificate x509-client.pem \
 212   --outder --outfile x509-client.p12
 213 @end example
 214
 215 For icing, we'll create a proxy certificate for the client too.
 216
 217 @example
 218 $ certtool --generate-privkey > x509-proxy-key.pem
 219 $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
 220 $ certtool --generate-proxy --load-privkey x509-proxy-key.pem \
 221   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
 222   --load-certificate x509-client.pem --template proxy.tmpl \
 223   --outfile x509-proxy.pem
 224 ...
 225 @end example
 226
 227 Then start the server again:
 228
 229 @example
 230 $ gnutls-serv --http \
 231             --x509cafile x509-ca.pem \
 232             --x509keyfile x509-server-key.pem \
 233             --x509certfile x509-server.pem
 234 @end example
 235
 236 Try connecting to the server using your web browser.  Note that the
 237 server listens to port 5556 by default.
 238
 239 While you are at it, to allow connections using DSA, you can also
 240 create a DSA key and certificate for the server.  These credentials
 241 will be used in the final example below.
 242
 243 @example
 244 $ certtool --generate-privkey --dsa > x509-server-key-dsa.pem
 245 $ certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
 246   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 247   --template server.tmpl --outfile x509-server-dsa.pem
 248 ...
 249 @end example
 250
 251 The next step is to create OpenPGP credentials for the server.
 252
 253 @example
 254 gpg --gen-key
 255 ...enter whatever details you want, use 'test.gnutls.org' as name...
 256 @end example
 257
 258 Make a note of the OpenPGP key identifier of the newly generated key,
 259 here it was @code{5D1D14D8}.  You will need to export the key for
 260 GnuTLS to be able to use it.
 261
 262 @example
 263 gpg -a --export 5D1D14D8 > openpgp-server.txt
 264 gpg --export 5D1D14D8 > openpgp-server.bin
 265 gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
 266 gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
 267 @end example
 268
 269 Let's start the server with support for OpenPGP credentials:
 270
 271 @example
 272 gnutls-serv --http \
 273             --pgpkeyfile openpgp-server-key.txt \
 274             --pgpcertfile openpgp-server.txt
 275 @end example
 276
 277 The next step is to add support for SRP authentication. This requires
 278 an SRP password file created with @code{srptool}.
 279 To start the server with SRP support:
 280
 281 @example
 282 gnutls-serv --http \
 283             --srppasswdconf srp-tpasswd.conf \
 284             --srppasswd srp-passwd.txt
 285 @end example
 286
 287 Let's also start a server with support for PSK. This would require
 288 a password file created with @code{psktool}.
 289
 290 @example
 291 gnutls-serv --http \
 292             --pskpasswd psk-passwd.txt
 293 @end example
 294
 295 Finally, we start the server with all the earlier parameters and you
 296 get this command:
 297
 298 @example
 299 gnutls-serv --http \
 300             --x509cafile x509-ca.pem \
 301             --x509keyfile x509-server-key.pem \
 302             --x509certfile x509-server.pem \
 303             --x509dsakeyfile x509-server-key-dsa.pem \
 304             --x509dsacertfile x509-server-dsa.pem \
 305             --pgpkeyfile openpgp-server-key.txt \
 306             --pgpcertfile openpgp-server.txt \
 307             --srppasswdconf srp-tpasswd.conf \
 308             --srppasswd srp-passwd.txt \
 309             --pskpasswd psk-passwd.txt
 310 @end example
 311