1gnutls-serv(1) User Commands gnutls-serv(1)
2
6 gnutls-serv - GnuTLS server
7
9 gnutls-serv [-flags] [-flag [value]] [--option-name[[=| ]value]]
10 All arguments must be options.
12
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 Specifies the debug level.
24 --sni-hostname=string
26 Server's hostname for server name extension.
27 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 --sni-hostname-fatal
33 Send fatal alert on sni-hostname mismatch.
34 --alpn=string
37 Specify ALPN protocol to be enabled by the server. This option
38 may appear an unlimited number of times.
39 Specify the (textual) ALPN protocol for the server to use.
41 --alpn-fatal
43 Send fatal alert on non-matching ALPN name.
44 --noticket
47 Don't accept session tickets.
48 --earlydata
51 Accept early data.
52 --maxearlydata=number
55 The maximum early data size to accept. This option takes an in‐
56 teger number as its argument. The value of number is con‐
57 strained to being:
58 greater than or equal to 1
59 --nocookie
62 Don't require cookie on DTLS sessions.
63 -g, --generate
66 Generate Diffie-Hellman parameters.
67 -q, --quiet
70 Suppress some messages.
71 --nodb Do not use a resumption database.
74 --http Act as an HTTP server.
77 --echo Act as an Echo server.
80 --crlf Do not replace CRLF by LF in Echo server mode.
83 -u, --udp
86 Use DTLS (datagram TLS) over UDP.
87 --mtu=number
90 Set MTU for datagram TLS. This option takes an integer number
91 as its argument. The value of number is constrained to being:
92 in the range 0 through 17000
93 --srtp-profiles=string
96 Offer SRTP profiles.
97 -a, --disable-client-cert
100 Do not request a client certificate. This option must not ap‐
101 pear in combination with any of the following options: require-
102 client-cert.
103 -r, --require-client-cert
106 Require a client certificate.
107 This option before 3.6.0 used to imply --verify-client-cert.
109 Since 3.6.0 it will no longer verify the certificate by default.
110 --verify-client-cert
112 If a client certificate is sent then verify it..
113 Do not require, but if a client certificate is sent then verify
115 it and close the connection if invalid.
116 -b, --heartbeat
118 Activate heartbeat support.
119 Regularly ping client via heartbeat extension messages
121 --x509fmtder
123 Use DER format for certificates to read from.
124 --priority=string
127 Priorities string.
128 TLS algorithms and protocols to enable. You can use predefined
130 sets of ciphersuites such as PERFORMANCE, NORMAL, SECURE128, SE‐
131 CURE256. The default is NORMAL.
132 Check the GnuTLS manual on section “Priority strings” for
134 more information on allowed keywords
135 --dhparams=file
137 DH params file to use.
138 --x509cafile=string
141 Certificate file or PKCS #11 URL to use.
142 --x509crlfile=file
145 CRL file to use.
146 --pgpkeyfile=file
149 PGP Key file to use.
150 NOTE: THIS OPTION IS DEPRECATED
153 --x509keyfile=string
155 X.509 key file or PKCS #11 URL to use. This option may appear
156 an unlimited number of times.
157 Specify the private key file or URI to use; it must correspond
159 to the certificate specified in --x509certfile. Multiple keys
160 and certificates can be specified with this option and in that
161 case each occurrence of keyfile must be followed by the corre‐
162 sponding x509certfile or vice-versa.
163 --x509certfile=string
165 X.509 Certificate file or PKCS #11 URL to use. This option may
166 appear an unlimited number of times.
167 Specify the certificate file or URI to use; it must correspond
169 to the key specified in --x509keyfile. Multiple keys and cer‐
170 tificates can be specified with this option and in that case
171 each occurrence of keyfile must be followed by the corresponding
172 x509certfile or vice-versa.
173 --x509dsakeyfile
175 This is an alias for the --x509keyfile option.
176 NOTE: THIS OPTION IS DEPRECATED
178 --x509dsacertfile
180 This is an alias for the --x509certfile option.
181 NOTE: THIS OPTION IS DEPRECATED
183 --x509ecckeyfile
185 This is an alias for the --x509keyfile option.
186 NOTE: THIS OPTION IS DEPRECATED
188 --x509ecccertfile
190 This is an alias for the --x509certfile option.
191 NOTE: THIS OPTION IS DEPRECATED
193 --rawpkkeyfile=string
195 Private key file (PKCS #8 or PKCS #12) or PKCS #11 URL to use.
196 This option may appear an unlimited number of times.
197 Specify the private key file or URI to use; it must correspond
199 to the raw public-key specified in --rawpkfile. Multiple key
200 pairs can be specified with this option and in that case each
201 occurrence of keyfile must be followed by the corresponding raw‐
202 pkfile or vice-versa.
203 In order to instruct the application to negotiate raw public
205 keys one must enable the respective certificate types via the
206 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
207 Check the GnuTLS manual on section “Priority strings” for
209 more information on how to set certificate types.
210 --rawpkfile=string
212 Raw public-key file to use. This option may appear an unlimited
213 number of times. This option must appear in combination with
214 the following options: rawpkkeyfile.
215 Specify the raw public-key file to use; it must correspond to
217 the private key specified in --rawpkkeyfile. Multiple key pairs
218 can be specified with this option and in that case each occur‐
219 rence of keyfile must be followed by the corresponding rawpkfile
220 or vice-versa.
221 In order to instruct the application to negotiate raw public
223 keys one must enable the respective certificate types via the
224 priority strings (i.e. CTYPE-CLI-* and CTYPE-SRV-* flags).
225 Check the GnuTLS manual on section “Priority strings” for
227 more information on how to set certificate types.
228 --srppasswd=file
230 SRP password file to use.
231 --srppasswdconf=file
234 SRP password configuration file to use.
235 --pskpasswd=file
238 PSK password file to use.
239 --pskhint=string
242 PSK identity hint to use.
243 --ocsp-response=string
246 The OCSP response to send to client. This option may appear an
247 unlimited number of times.
248 If the client requested an OCSP response, return data from this
250 file to the client.
251 --ignore-ocsp-response-errors
253 Ignore any errors when setting the OCSP response.
254 That option instructs gnutls to not attempt to match the pro‐
256 vided OCSP responses with the certificates.
257 -p number, --port=number
259 The port to connect to. This option takes an integer number as
260 its argument.
261 -l, --list
264 Print a list of the supported algorithms and modes.
265 Print a list of the supported algorithms and modes. If a prior‐
267 ity string is given then only the enabled ciphersuites are
268 shown.
269 --provider=file
271 Specify the PKCS #11 provider library.
272 This will override the default options in
274 /etc/gnutls/pkcs11.conf
275 --keymatexport=string
277 Label used for exporting keying material.
278 --keymatexportsize=number
281 Size of the exported keying material. This option takes an in‐
282 teger number as its argument.
283 --recordsize=number
286 The maximum record size to advertise. This option takes an in‐
287 teger number as its argument. The value of number is con‐
288 strained to being:
289 in the range 0 through 16384
290 --httpdata=file
293 The data used as HTTP response.
294 -h, --help
297 Display usage information and exit.
298 -!, --more-help
300 Pass the extended usage information through a pager.
301 -v [{v|c|n --version [{v|c|n}]}]
303 Output version of program and exit. The default mode is `v', a
304 simple version. The `c' mode will print copyright information
305 and `n' will print the full copyright notice.
306
308 Running your own TLS server based on GnuTLS can be useful when debug‐
309 ging clients and/or GnuTLS itself. This section describes how to use
310 gnutls-serv as a simple HTTPS server.
311 The most basic server can be started as:
313 gnutls-serv --http --priority "NORMAL:+ANON-ECDH:+ANON-DH"
315 It will only support anonymous ciphersuites, which many TLS clients
317 refuse to use.
318 The next step is to add support for X.509. First we generate a CA:
320 $ certtool --generate-privkey > x509-ca-key.pem
322 $ echo 'cn = GnuTLS test CA' > ca.tmpl
323 $ echo 'ca' >> ca.tmpl
324 $ echo 'cert_signing_key' >> ca.tmpl
325 $ certtool --generate-self-signed --load-privkey x509-ca-key.pem --template ca.tmpl --outfile x509-ca.pem
326 Then generate a server certificate. Remember to change the dns_name
328 value to the name of your server host, or skip that command to avoid
329 the field.
330 $ certtool --generate-privkey > x509-server-key.pem
332 $ echo 'organization = GnuTLS test server' > server.tmpl
333 $ echo 'cn = test.gnutls.org' >> server.tmpl
334 $ echo 'tls_www_server' >> server.tmpl
335 $ echo 'encryption_key' >> server.tmpl
336 $ echo 'signing_key' >> server.tmpl
337 $ echo 'dns_name = test.gnutls.org' >> server.tmpl
338 $ 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
339 For use in the client, you may want to generate a client certificate as
341 well.
342 $ certtool --generate-privkey > x509-client-key.pem
344 $ echo 'cn = GnuTLS test client' > client.tmpl
345 $ echo 'tls_www_client' >> client.tmpl
346 $ echo 'encryption_key' >> client.tmpl
347 $ echo 'signing_key' >> client.tmpl
348 $ 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
349 To be able to import the client key/certificate into some applications,
351 you will need to convert them into a PKCS#12 structure. This also en‐
352 crypts the security sensitive key with a password.
353 $ 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
355 For icing, we'll create a proxy certificate for the client too.
357 $ certtool --generate-privkey > x509-proxy-key.pem
359 $ echo 'cn = GnuTLS test client proxy' > proxy.tmpl
360 $ 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
361 Then start the server again:
363 $ gnutls-serv --http --x509cafile x509-ca.pem --x509keyfile x509-server-key.pem --x509certfile x509-server.pem
365 Try connecting to the server using your web browser. Note that the
367 server listens to port 5556 by default.
368 While you are at it, to allow connections using ECDSA, you can also
370 create a ECDSA key and certificate for the server. These credentials
371 will be used in the final example below.
372 $ certtool --generate-privkey --ecdsa > x509-server-key-ecc.pem
374 $ 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
375 The next step is to add support for SRP authentication. This requires
378 an SRP password file created with srptool. To start the server with
379 SRP support:
380 gnutls-serv --http --priority NORMAL:+SRP-RSA:+SRP --srppasswdconf srp-tpasswd.conf --srppasswd srp-passwd.txt
382 Let's also start a server with support for PSK. This would require a
384 password file created with psktool.
385 gnutls-serv --http --priority NORMAL:+ECDHE-PSK:+PSK --pskpasswd psk-passwd.txt
387 If you want a server with support for raw public-keys we can also add
389 these credentials. Note however that there is no identity information
390 linked to these keys as is the case with regular x509 certificates. Au‐
391 thentication must be done via different means. Also we need to explic‐
392 itly enable raw public-key certificates via the priority strings.
393 gnutls-serv --http --priority NORMAL:+CTYPE-CLI-RAWPK:+CTYPE-SRV-RAWPK --rawpkfile srv.rawpk.pem --rawpkkeyfile srv.key.pem
395 Finally, we start the server with all the earlier parameters and you
398 get this command:
399 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
401
403 One of the following exit values will be returned:
404 0 (EXIT_SUCCESS)
406 Successful program execution.
407 1 (EXIT_FAILURE)
409 The operation failed or the command syntax was not valid.
410 70 (EX_SOFTWARE)
412 libopts had an internal operational error. Please report it to
413 autogen-users@lists.sourceforge.net. Thank you.
414
416 gnutls-cli-debug(1), gnutls-cli(1)
417
419 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
420 /usr/share/doc/gnutls/AUTHORS for a complete list.
421
423 Copyright (C) 2000-2020 Free Software Foundation, and others all rights
424 reserved. This program is released under the terms of the GNU General
425 Public License, version 3 or later.
426
428 Please send bug reports to: bugs@gnutls.org
429
431 This manual page was AutoGen-erated from the gnutls-serv option defini‐
432 tions.
4333.7.2 29 May 2021 gnutls-serv(1)