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