1 @node gnutls-cli Invocation
2 @section Invoking gnutls-cli
6 # -*- buffer-read-only: t -*- vi: set ro:
8 # DO NOT EDIT THIS FILE (invoke-gnutls-cli.texi)
10 # It has been AutoGen-ed September 1, 2012 at 11:10:28 AM by AutoGen 5.16
11 # From the definitions ../src/cli-args.def
12 # and the template file agtexi-cmd.tpl
16 Simple client program to set up a TLS connection to some other computer.
17 It sets up a TLS connection and forwards data from the standard input to the secured socket and vice versa.
19 This section was generated by @strong{AutoGen},
20 using the @code{agtexi-cmd} template and the option descriptions for the @code{gnutls-cli} program.
21 This software is released under the GNU General Public License, version 3 or later.
24 @anchor{gnutls-cli usage}
25 @subheading gnutls-cli help/usage (-h)
26 @cindex gnutls-cli help
28 This is the automatically generated usage text for gnutls-cli.
29 The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!). @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.
38 gnutls-cli - GnuTLS client - Ver. @@VERSION@@
39 USAGE: gnutls-cli [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [hostname]
41 -d, --debug=num Enable debugging.
42 - It must be in the range:
44 -V, --verbose More verbose output
45 - may appear multiple times
46 --tofu Enable trust on first use authentication
47 - disabled as --no-tofu
48 --ocsp Enable OCSP certificate verification
49 - disabled as --no-ocsp
50 -r, --resume Establish a session and resume
51 -b, --heartbeat Activate heartbeat support
52 -e, --rehandshake Establish a session and rehandshake
53 --noticket Don't accept session tickets
54 -s, --starttls Connect, establish a plain session and start TLS.
55 -u, --udp Use DTLS (datagram TLS) over UDP
56 --mtu=num Set MTU for datagram TLS
57 - It must be in the range:
59 --crlf Send CR LF instead of LF
60 --x509fmtder Use DER format for certificates to read from
61 -f, --fingerprint Send the openpgp fingerprint, instead of the key
62 --disable-extensions Disable all the TLS extensions
63 --print-cert Print peer's certificate in PEM format
64 --recordsize=num The maximum record size to advertize
65 - It must be in the range:
67 --dh-bits=num The minimum number of bits allowed for DH
68 --priority=str Priorities string
69 --x509cafile=str Certificate file or PKCS #11 URL to use
70 --x509crlfile=file CRL file to use
72 --pgpkeyfile=file PGP Key file to use
74 --pgpkeyring=file PGP Key ring file to use
76 --pgpcertfile=file PGP Public Key (certificate) file to use
78 --x509keyfile=str X.509 key file or PKCS #11 URL to use
79 --x509certfile=str X.509 Certificate file or PKCS #11 URL to use
80 --pgpsubkey=str PGP subkey to use (hex or auto)
81 --srpusername=str SRP username to use
82 --srppasswd=str SRP password to use
83 --pskusername=str PSK username to use
84 --pskkey=str PSK key (in hex) to use
85 -p, --port=str The port or service to connect to
86 --insecure Don't abort program if server certificate can't be validated
87 --benchmark-ciphers Benchmark individual ciphers
88 --benchmark-soft-ciphers Benchmark individual software ciphers (no hw acceleration)
89 --benchmark-tls-kx Benchmark TLS key exchange methods
90 --benchmark-tls-ciphers Benchmark TLS ciphers
91 -l, --list Print a list of the supported algorithms and modes
92 -v, --version[=arg] Output version information and exit
93 -h, --help Display extended usage information and exit
94 -!, --more-help Extended usage information passed thru pager
96 Options are specified by doubled hyphens and their name or by a single
97 hyphen and the flag character.
98 Operands and options may be intermixed. They will be reordered.
102 Simple client program to set up a TLS connection to some other computer. It
103 sets up a TLS connection and forwards data from the standard input to the
104 secured socket and vice versa.
106 please send bug reports to: bug-gnutls@@gnu.org
110 @anchor{gnutls-cli debug}
111 @subheading debug option (-d)
112 @cindex gnutls-cli-debug
114 This is the ``enable debugging.'' option.
115 This option takes an argument number.
116 Specifies the debug level.
117 @anchor{gnutls-cli tofu}
118 @subheading tofu option
119 @cindex gnutls-cli-tofu
121 This is the ``enable trust on first use authentication'' option.
122 This option will, in addition to certificate authentication, perform authentication based on previously seen public keys, a model similar to SSH authentication.
123 @anchor{gnutls-cli ocsp}
124 @subheading ocsp option
125 @cindex gnutls-cli-ocsp
127 This is the ``enable ocsp certificate verification'' option.
128 This option will enable verification of the peer's certificate using ocsp
129 @anchor{gnutls-cli resume}
130 @subheading resume option (-r)
131 @cindex gnutls-cli-resume
133 This is the ``establish a session and resume'' option.
134 Connect, establish a session, reconnect and resume.
135 @anchor{gnutls-cli rehandshake}
136 @subheading rehandshake option (-e)
137 @cindex gnutls-cli-rehandshake
139 This is the ``establish a session and rehandshake'' option.
140 Connect, establish a session and rehandshake immediately.
141 @anchor{gnutls-cli starttls}
142 @subheading starttls option (-s)
143 @cindex gnutls-cli-starttls
145 This is the ``connect, establish a plain session and start tls.'' option.
146 The TLS session will be initiated when EOF or a SIGALRM is received.
147 @anchor{gnutls-cli dh-bits}
148 @subheading dh-bits option
149 @cindex gnutls-cli-dh-bits
151 This is the ``the minimum number of bits allowed for dh'' option.
152 This option takes an argument number.
153 This option sets the minimum number of bits allowed for a Diffie-Hellman key exchange. You may want to lower the default value if the peer sends a weak prime and you get an connection error with unacceptable prime.
154 @anchor{gnutls-cli priority}
155 @subheading priority option
156 @cindex gnutls-cli-priority
158 This is the ``priorities string'' option.
159 This option takes an argument string.
160 TLS algorithms and protocols to enable. You can
161 use predefined sets of ciphersuites such as PERFORMANCE,
162 NORMAL, SECURE128, SECURE256.
164 Check the GnuTLS manual on section ``Priority strings'' for more
165 information on allowed keywords
166 @anchor{gnutls-cli list}
167 @subheading list option (-l)
168 @cindex gnutls-cli-list
170 This is the ``print a list of the supported algorithms and modes'' option.
171 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
172 @anchor{gnutls-cli exit status}
173 @subheading gnutls-cli exit status
175 One of the following exit values will be returned:
177 @item 0 (EXIT_SUCCESS)
178 Successful program execution.
179 @item 1 (EXIT_FAILURE)
180 The operation failed or the command syntax was not valid.
182 @anchor{gnutls-cli See Also}
183 @subheading gnutls-cli See Also
184 gnutls-cli-debug(1), gnutls-serv(1)
186 @anchor{gnutls-cli Examples}
187 @subheading gnutls-cli Examples
188 @subheading Connecting using PSK authentication
189 To connect to a server using PSK authentication, you need to enable the choice of PSK by using a cipher priority parameter such as in the example below.
191 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
192 --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
193 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
194 Resolving 'localhost'...
195 Connecting to '127.0.0.1:5556'...
196 - PSK authentication.
199 - Cipher: AES-128-CBC
202 - Handshake was completed
204 - Simple Client Mode:
206 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.
208 @subheading Listing ciphersuites in a priority string
209 To list the ciphersuites in a priority string:
211 $ ./gnutls-cli --priority SECURE192 -l
212 Cipher suites for SECURE192
213 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
214 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
215 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
216 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
217 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
218 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
220 Certificate types: CTYPE-X.509
221 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
222 Compression: COMP-NULL
223 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
224 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512