1gnutls-serv(1)                   User Commands                  gnutls-serv(1)
2
3
4

NAME

6       gnutls-serv - GnuTLS server
7

SYNOPSIS

9       gnutls-serv [-flags] [-flag [value]] [--option-name[[=| ]value]]
10
11       All arguments must be options.
12
13

DESCRIPTION

15       Server program that listens to incoming TLS connections.
16

OPTIONS

18       -d number, --debug=number
19              Enable  debugging.   This  option takes an integer number as its
20              argument.  The value of number is constrained to being:
21                  in the range  0 through 9999
22
23              Specifies the debug level.
24
25       --sni-hostname=string
26              Server's hostname for server name extension.
27
28              Server name of type host_name that the server will recognise as
29              its own. If the server receives client hello with different
30              name, it will send a warning-level unrecognized_name alert.
31
32       --sni-hostname-fatal
33              Send fatal alert on sni-hostname mismatch.
34
35
36       --alpn=string
37              Specify ALPN protocol to be enabled by the server.  This option
38              may appear an unlimited number of times.
39
40              Specify the (textual) ALPN protocol for the server to use.
41
42       --alpn-fatal
43              Send fatal alert on non-matching ALPN name.
44
45
46       --noticket
47              Don't accept session tickets.
48
49
50       --earlydata
51              Accept early data.
52
53
54       --maxearlydata=number
55              The maximum early data size to accept.  This option takes an
56              integer number as its argument.  The value of number is con‐
57              strained to being:
58                  in the range  1 through 4294967295
59
60
61       --nocookie
62              Don't require cookie on DTLS sessions.
63
64
65       -g, --generate
66              Generate Diffie-Hellman parameters.
67
68
69       -q, --quiet
70              Suppress some messages.
71
72
73       --nodb Do not use a resumption database.
74
75
76       --http Act as an HTTP server.
77
78
79       --echo Act as an Echo server.
80
81
82       -u, --udp
83              Use DTLS (datagram TLS) over UDP.
84
85
86       --mtu=number
87              Set MTU for datagram TLS.  This option takes an integer number
88              as its argument.  The value of number is constrained to being:
89                  in the range  0 through 17000
90
91
92       --srtp-profiles=string
93              Offer SRTP profiles.
94
95
96       -a, --disable-client-cert
97              Do not request a client certificate.  This option must not
98              appear in combination with any of the following options:
99              require-client-cert.
100
101
102       -r, --require-client-cert
103              Require a client certificate.
104
105              This option before 3.6.0 used to imply --verify-client-cert.
106              Since 3.6.0 it will no longer verify the certificate by default.
107
108       --verify-client-cert
109              If a client certificate is sent then verify it..
110
111              Do not require, but if a client certificate is sent then verify
112              it and close the connection if invalid.
113
114       -b, --heartbeat
115              Activate heartbeat support.
116
117              Regularly ping client via heartbeat extension messages
118
119       --x509fmtder
120              Use DER format for certificates to read from.
121
122
123       --priority=string
124              Priorities string.
125
126              TLS algorithms and protocols to enable. You can use predefined
127              sets of ciphersuites such as PERFORMANCE, NORMAL, SECURE128,
128              SECURE256. The default is NORMAL.
129
130              Check  the  GnuTLS  manual  on  section  “Priority strings” for
131              more information on allowed keywords
132
133       --dhparams=file
134              DH params file to use.
135
136
137       --x509cafile=string
138              Certificate file or PKCS #11 URL to use.
139
140
141       --x509crlfile=file
142              CRL file to use.
143
144
145       --pgpkeyfile=file
146              PGP Key file to use.
147
148
149              NOTE: THIS OPTION IS DEPRECATED
150
151       --x509keyfile=string
152              X.509 key file or PKCS #11 URL to use.  This option may appear
153              an unlimited number of times.
154
155              Specify the private key file or URI to use; it must correspond
156              to the certificate specified in --x509certfile. Multiple keys
157              and certificates can be specified with this option and in that
158              case each occurrence of keyfile must be followed by the corre‐
159              sponding x509certfile or vice-versa.
160
161       --x509certfile=string
162              X.509 Certificate file or PKCS #11 URL to use.  This option may
163              appear an unlimited number of times.
164
165              Specify the certificate file or URI to use; it must correspond
166              to the key specified in --x509keyfile. Multiple keys and cer‐
167              tificates can be specified with this option and in that case
168              each occurrence of keyfile must be followed by the corresponding
169              x509certfile or vice-versa.
170
171       --x509dsakeyfile
172              This is an alias for the --x509keyfile option.
173
174              NOTE: THIS OPTION IS DEPRECATED
175
176       --x509dsacertfile
177              This is an alias for the --x509certfile option.
178
179              NOTE: THIS OPTION IS DEPRECATED
180
181       --x509ecckeyfile
182              This is an alias for the --x509keyfile option.
183
184              NOTE: THIS OPTION IS DEPRECATED
185
186       --x509ecccertfile
187              This is an alias for the --x509certfile option.
188
189              NOTE: THIS OPTION IS DEPRECATED
190
191       --rawpkkeyfile=string
192              Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
193              This option may appear an unlimited number of times.
194
195              Specify the private key file or URI to use; it must correspond
196              to the raw public-key specified in --rawpkfile. Multiple key
197              pairs can be specified with this option and in that case each
198              occurrence of keyfile must be followed by the corresponding raw‐
199              pkfile or vice-versa.
200
201              In order to instruct the application to negotiate raw public
202              keys one must enable the respective certificate types via the
203              priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
204
205              Check  the  GnuTLS  manual  on  section  “Priority strings” for
206              more information on how to set certificate types.
207
208       --rawpkfile=string
209              Raw public-key file to use.  This option may appear an unlimited
210              number of times.  This option must appear in combination with
211              the following options: rawpkkeyfile.
212
213              Specify the raw public-key file to use; it must correspond to
214              the private key specified in --rawpkkeyfile. Multiple key pairs
215              can be specified with this option and in that case each occur‐
216              rence of keyfile must be followed by the corresponding rawpkfile
217              or vice-versa.
218
219              In order to instruct the application to negotiate raw public
220              keys one must enable the respective certificate types via the
221              priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
222
223              Check  the  GnuTLS  manual  on  section  “Priority strings” for
224              more information on how to set certificate types.
225
226       --srppasswd=file
227              SRP password file to use.
228
229
230       --srppasswdconf=file
231              SRP password configuration file to use.
232
233
234       --pskpasswd=file
235              PSK password file to use.
236
237
238       --pskhint=string
239              PSK identity hint to use.
240
241
242       --ocsp-response=string
243              The OCSP response to send to client.  This option may appear an
244              unlimited number of times.
245
246              If the client requested an OCSP response, return data from this
247              file to the client.
248
249       --ignore-ocsp-response-errors
250              Ignore any errors when setting the OCSP response.
251
252              That option instructs gnutls to not attempt to match the pro‐
253              vided OCSP responses with the certificates.
254
255       -p number, --port=number
256              The port to connect to.  This option takes an integer number as
257              its argument.
258
259
260       -l, --list
261              Print a list of the supported algorithms and modes.
262
263              Print a list of the supported algorithms and modes. If a prior‐
264              ity string is given then only the enabled ciphersuites are
265              shown.
266
267       --provider=file
268              Specify the PKCS #11 provider library.
269
270              This will override the default options in
271              /etc/gnutls/pkcs11.conf
272
273       --keymatexport=string
274              Label used for exporting keying material.
275
276
277       --keymatexportsize=number
278              Size of the exported keying material.  This option takes an
279              integer number as its argument.
280
281
282       --recordsize=number
283              The maximum record size to advertise.  This option takes an
284              integer number as its argument.  The value of number is con‐
285              strained to being:
286                  in the range  0 through 16384
287
288
289       --httpdata=file
290              The data used as HTTP response.
291
292
293       -h, --help
294              Display usage information and exit.
295
296       -!, --more-help
297              Pass the extended usage information through a pager.
298
299       -v [{v|c|n --version [{v|c|n}]}]
300              Output version of program and exit.  The default mode is `v', a
301              simple version.  The `c' mode will print copyright information
302              and `n' will print the full copyright notice.
303

EXAMPLES

305       Running your own TLS server based on GnuTLS can be useful when debug‐
306       ging clients and/or GnuTLS itself.  This section describes how to use
307       gnutls-serv as a simple HTTPS server.
308
309       The most basic server can be started as:
310
311           gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH"
312
313       It will only support anonymous ciphersuites, which many TLS clients
314       refuse to use.
315
316       The next step is to add support for X.509.  First we generate a CA:
317
318           $ certtool --generate-privkey > x509-ca-key.pem
319           $ echo 'cn = GnuTLS test CA' > ca.tmpl
320           $ echo 'ca' >> ca.tmpl
321           $ echo 'cert_signing_key' >> ca.tmpl
322           $ certtool --generate-self-signed --load-privkey x509-ca-key.pem   --template ca.tmpl --outfile x509-ca.pem
323
324       Then generate a server certificate.  Remember to change the dns_name
325       value to the name of your server host, or skip that command to avoid
326       the field.
327
328           $ certtool --generate-privkey > x509-server-key.pem
329           $ echo 'organization = GnuTLS test server' > server.tmpl
330           $ echo 'cn = test.gnutls.org' >> server.tmpl
331           $ echo 'tls_www_server' >> server.tmpl
332           $ echo 'encryption_key' >> server.tmpl
333           $ echo 'signing_key' >> server.tmpl
334           $ echo 'dns_name = test.gnutls.org' >> server.tmpl
335           $ certtool --generate-certificate --load-privkey x509-server-key.pem   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem   --template server.tmpl --outfile x509-server.pem
336
337       For use in the client, you may want to generate a client certificate as
338       well.
339
340           $ certtool --generate-privkey > x509-client-key.pem
341           $ echo 'cn = GnuTLS test client' > client.tmpl
342           $ echo 'tls_www_client' >> client.tmpl
343           $ echo 'encryption_key' >> client.tmpl
344           $ echo 'signing_key' >> client.tmpl
345           $ certtool --generate-certificate --load-privkey x509-client-key.pem   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem   --template client.tmpl --outfile x509-client.pem
346
347       To be able to import the client key/certificate into some applications,
348       you will need to convert them into a PKCS#12 structure.  This also
349       encrypts the security sensitive key with a password.
350
351           $ certtool --to-p12 --load-ca-certificate x509-ca.pem   --load-privkey x509-client-key.pem --load-certificate x509-client.pem   --outder --outfile x509-client.p12
352
353       For icing, we'll create a proxy certificate for the client too.
354
355           $ certtool --generate-privkey > x509-proxy-key.pem
356           $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
357           $ certtool --generate-proxy --load-privkey x509-proxy-key.pem   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem   --load-certificate x509-client.pem --template proxy.tmpl   --outfile x509-proxy.pem
358
359       Then start the server again:
360
361           $ gnutls-serv --http             --x509cafile x509-ca.pem             --x509keyfile x509-server-key.pem             --x509certfile x509-server.pem
362
363       Try connecting to the server using your web browser.  Note that the
364       server listens to port 5556 by default.
365
366       While you are at it, to allow connections using ECDSA, you can also
367       create a ECDSA key and certificate for the server.  These credentials
368       will be used in the final example below.
369
370           $ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem
371           $ certtool --generate-certificate --load-privkey x509-server-key-ecc.pem   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem   --template server.tmpl --outfile x509-server-ecc.pem
372
373
374       The next step is to add support for SRP authentication. This requires
375       an SRP password file created with srptool.  To start the server with
376       SRP support:
377
378           gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP             --srppasswdconf srp-tpasswd.conf             --srppasswd srp-passwd.txt
379
380       Let's also start a server with support for PSK. This would require a
381       password file created with psktool.
382
383           gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK             --pskpasswd psk-passwd.txt
384
385       If you want a server with support for raw public-keys we can also add
386       these credentials. Note however that there is no identity information
387       linked to these keys as is the case with regular x509 certificates.
388       Authentication must be done via different means. Also we need to
389       explicitly enable raw public-key certificates via the priority strings.
390
391           gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK             --rawpkfile srv.rawpk.pem             --rawpkkeyfile srv.key.pem
392
393
394       Finally, we start the server with all the earlier parameters and you
395       get this command:
396
397           gnutls-serv --http --priority NORMAL:+PSK:+SRP:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK             --x509cafile x509-ca.pem             --x509keyfile x509-server-key.pem             --x509certfile x509-server.pem             --x509keyfile x509-server-key-ecc.pem             --x509certfile x509-server-ecc.pem             --srppasswdconf srp-tpasswd.conf             --srppasswd srp-passwd.txt             --pskpasswd psk-passwd.txt             --rawpkfile srv.rawpk.pem             --rawpkkeyfile srv.key.pem
398

EXIT STATUS

400       One of the following exit values will be returned:
401
402       0  (EXIT_SUCCESS)
403              Successful program execution.
404
405       1  (EXIT_FAILURE)
406              The operation failed or the command syntax was not valid.
407
408       70  (EX_SOFTWARE)
409              libopts had an internal operational error.  Please report it to
410              autogen-users@lists.sourceforge.net.  Thank you.
411

SEE ALSO

413       gnutls-cli-debug(1), gnutls-cli(1)
414

AUTHORS

416       Nikos Mavrogiannopoulos, Simon Josefsson and others; see
417       /usr/share/doc/gnutls/AUTHORS for a complete list.
418
420       Copyright (C) 2000-2019 Free Software Foundation, and others all rights
421       reserved.  This program is released under the terms of the GNU General
422       Public License, version 3 or later.
423

BUGS

425       Please send bug reports to: bugs@gnutls.org
426

NOTES

428       This manual page was AutoGen-erated from the gnutls-serv option defini‐
429       tions.
430
431
432
4333.6.11                            29 Nov 2019                   gnutls-serv(1)
Impressum