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