1gnutls-serv(1) User Commands gnutls-serv(1)
2
3
4
6 gnutls-serv - GnuTLS server
7
9 gnutls-serv [-flags] [-flag [value]] [--option-name[[=| ]value]]
10
11 All arguments must be options.
12
13
15 Server program that listens to incoming TLS connections.
16
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
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
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
413 gnutls-cli-debug(1), gnutls-cli(1)
414
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
425 Please send bug reports to: bugs@gnutls.org
426
428 This manual page was AutoGen-erated from the gnutls-serv option defini‐
429 tions.
430
431
432
4333.6.11 01 Dec 2019 gnutls-serv(1)