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 30, 2012 at 04:41:48 PM 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 --ocsp-status-request Enable OCSP status request
55 -s, --starttls Connect, establish a plain session and start TLS.
56 -u, --udp Use DTLS (datagram TLS) over UDP
57 --mtu=num Set MTU for datagram TLS
58 - It must be in the range:
60 --crlf Send CR LF instead of LF
61 --x509fmtder Use DER format for certificates to read from
62 -f, --fingerprint Send the openpgp fingerprint, instead of the key
63 --disable-extensions Disable all the TLS extensions
64 --print-cert Print peer's certificate in PEM format
65 --recordsize=num The maximum record size to advertize
66 - It must be in the range:
68 --dh-bits=num The minimum number of bits allowed for DH
69 --priority=str Priorities string
70 --x509cafile=str Certificate file or PKCS #11 URL to use
71 --x509crlfile=file CRL file to use
73 --pgpkeyfile=file PGP Key file to use
75 --pgpkeyring=file PGP Key ring file to use
77 --pgpcertfile=file PGP Public Key (certificate) file to use
79 --x509keyfile=str X.509 key file or PKCS #11 URL to use
80 --x509certfile=str X.509 Certificate file or PKCS #11 URL to use
81 --pgpsubkey=str PGP subkey to use (hex or auto)
82 --srpusername=str SRP username to use
83 --srppasswd=str SRP password to use
84 --pskusername=str PSK username to use
85 --pskkey=str PSK key (in hex) to use
86 -p, --port=str The port or service to connect to
87 --insecure Don't abort program if server certificate can't be validated
88 --benchmark-ciphers Benchmark individual ciphers
89 --benchmark-soft-ciphers Benchmark individual software ciphers (no hw acceleration)
90 --benchmark-tls-kx Benchmark TLS key exchange methods
91 --benchmark-tls-ciphers Benchmark TLS ciphers
92 -l, --list Print a list of the supported algorithms and modes
93 -v, --version[=arg] Output version information and exit
94 -h, --help Display extended usage information and exit
95 -!, --more-help Extended usage information passed thru pager
97 Options are specified by doubled hyphens and their name or by a single
98 hyphen and the flag character.
99 Operands and options may be intermixed. They will be reordered.
103 Simple client program to set up a TLS connection to some other computer. It
104 sets up a TLS connection and forwards data from the standard input to the
105 secured socket and vice versa.
107 please send bug reports to: bug-gnutls@@gnu.org
111 @anchor{gnutls-cli debug}
112 @subheading debug option (-d)
113 @cindex gnutls-cli-debug
115 This is the ``enable debugging.'' option.
116 This option takes an argument number.
117 Specifies the debug level.
118 @anchor{gnutls-cli tofu}
119 @subheading tofu option
120 @cindex gnutls-cli-tofu
122 This is the ``enable trust on first use authentication'' option.
123 This option will, in addition to certificate authentication, perform authentication based on previously seen public keys, a model similar to SSH authentication.
124 @anchor{gnutls-cli ocsp}
125 @subheading ocsp option
126 @cindex gnutls-cli-ocsp
128 This is the ``enable ocsp certificate verification'' option.
129 This option will enable verification of the peer's certificate using ocsp
130 @anchor{gnutls-cli resume}
131 @subheading resume option (-r)
132 @cindex gnutls-cli-resume
134 This is the ``establish a session and resume'' option.
135 Connect, establish a session, reconnect and resume.
136 @anchor{gnutls-cli rehandshake}
137 @subheading rehandshake option (-e)
138 @cindex gnutls-cli-rehandshake
140 This is the ``establish a session and rehandshake'' option.
141 Connect, establish a session and rehandshake immediately.
142 @anchor{gnutls-cli ocsp-status-request}
143 @subheading ocsp-status-request option
144 @cindex gnutls-cli-ocsp-status-request
146 This is the ``enable ocsp status request'' option.
147 The client will indicate to the server in a TLS extension that it wants a OCSP status request.
148 @anchor{gnutls-cli starttls}
149 @subheading starttls option (-s)
150 @cindex gnutls-cli-starttls
152 This is the ``connect, establish a plain session and start tls.'' option.
153 The TLS session will be initiated when EOF or a SIGALRM is received.
154 @anchor{gnutls-cli dh-bits}
155 @subheading dh-bits option
156 @cindex gnutls-cli-dh-bits
158 This is the ``the minimum number of bits allowed for dh'' option.
159 This option takes an argument number.
160 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.
161 @anchor{gnutls-cli priority}
162 @subheading priority option
163 @cindex gnutls-cli-priority
165 This is the ``priorities string'' option.
166 This option takes an argument string.
167 TLS algorithms and protocols to enable. You can
168 use predefined sets of ciphersuites such as PERFORMANCE,
169 NORMAL, SECURE128, SECURE256.
171 Check the GnuTLS manual on section ``Priority strings'' for more
172 information on allowed keywords
173 @anchor{gnutls-cli list}
174 @subheading list option (-l)
175 @cindex gnutls-cli-list
177 This is the ``print a list of the supported algorithms and modes'' option.
178 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
179 @anchor{gnutls-cli exit status}
180 @subheading gnutls-cli exit status
182 One of the following exit values will be returned:
184 @item 0 (EXIT_SUCCESS)
185 Successful program execution.
186 @item 1 (EXIT_FAILURE)
187 The operation failed or the command syntax was not valid.
189 @anchor{gnutls-cli See Also}
190 @subheading gnutls-cli See Also
191 gnutls-cli-debug(1), gnutls-serv(1)
193 @anchor{gnutls-cli Examples}
194 @subheading gnutls-cli Examples
195 @subheading Connecting using PSK authentication
196 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.
198 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
199 --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
200 --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
201 Resolving 'localhost'...
202 Connecting to '127.0.0.1:5556'...
203 - PSK authentication.
206 - Cipher: AES-128-CBC
209 - Handshake was completed
211 - Simple Client Mode:
213 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.
215 @subheading Listing ciphersuites in a priority string
216 To list the ciphersuites in a priority string:
218 $ ./gnutls-cli --priority SECURE192 -l
219 Cipher suites for SECURE192
220 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384 0xc0, 0x24 TLS1.2
221 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384 0xc0, 0x2e TLS1.2
222 TLS_ECDHE_RSA_AES_256_GCM_SHA384 0xc0, 0x30 TLS1.2
223 TLS_DHE_RSA_AES_256_CBC_SHA256 0x00, 0x6b TLS1.2
224 TLS_DHE_DSS_AES_256_CBC_SHA256 0x00, 0x6a TLS1.2
225 TLS_RSA_AES_256_CBC_SHA256 0x00, 0x3d TLS1.2
227 Certificate types: CTYPE-X.509
228 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
229 Compression: COMP-NULL
230 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
231 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512