doc/invoke-gnutls-cli.texi

   1 @node gnutls-cli Invocation
   2 @section Invoking gnutls-cli
   3 @pindex gnutls-cli
   4 @ignore
   5 #  -*- buffer-read-only: t -*- vi: set ro:
   6 #
   7 # DO NOT EDIT THIS FILE   (invoke-gnutls-cli.texi)
   8 #
   9 # It has been AutoGen-ed
  10 # From the definitions    ../src/cli-args.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15 Simple client program to set up a TLS connection to some other computer.
  16 It sets up a TLS connection and forwards data from the standard input to the secured socket and vice versa.
  17
  18 This section was generated by @strong{AutoGen},
  19 using the @code{agtexi-cmd} template and the option descriptions for the @code{gnutls-cli} program.
  20 This software is released under the GNU General Public License, version 3 or later.
  21
  22
  23 @anchor{gnutls-cli usage}
  24 @subheading gnutls-cli help/usage (@option{--help})
  25 @cindex gnutls-cli help
  26
  27 This is the automatically generated usage text for gnutls-cli.
  28
  29 The text printed is the same whether selected with the @code{help} option
  30 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  31 the usage text by passing it through a pager program.
  32 @code{more-help} is disabled on platforms without a working
  33 @code{fork(2)} function.  The @code{PAGER} environment variable is
  34 used to select the program, defaulting to @file{more}.  Both will exit
  35 with a status code of 0.
  36
  37 @exampleindent 0
  38 @example
  39 gnutls-cli is unavailable - no --help
  40 @end example
  41 @exampleindent 4
  42
  43 @anchor{gnutls-cli debug}
  44 @subheading debug option (-d)
  45
  46 This is the ``enable debugging'' option.
  47 This option takes a number argument.
  48 Specifies the debug level.
  49 @anchor{gnutls-cli tofu}
  50 @subheading tofu option
  51
  52 This is the ``enable trust on first use authentication'' option.
  53
  54 @noindent
  55 This option has some usage constraints.  It:
  56 @itemize @bullet
  57 @item
  58 can be disabled with --no-tofu.
  59 @end itemize
  60
  61 This option will, in addition to certificate authentication, perform authentication
  62 based on previously seen public keys, a model similar to SSH authentication. Note that when tofu
  63 is specified (PKI) and DANE authentication will become advisory to assist the public key acceptance
  64 process.
  65 @anchor{gnutls-cli strict-tofu}
  66 @subheading strict-tofu option
  67
  68 This is the ``fail to connect if a known certificate has changed'' option.
  69
  70 @noindent
  71 This option has some usage constraints.  It:
  72 @itemize @bullet
  73 @item
  74 can be disabled with --no-strict-tofu.
  75 @end itemize
  76
  77 This option will perform authentication as with option --tofu; however, while --tofu asks whether to trust a changed public key, this option will fail in case of public key changes.
  78 @anchor{gnutls-cli dane}
  79 @subheading dane option
  80
  81 This is the ``enable dane certificate verification (dnssec)'' option.
  82
  83 @noindent
  84 This option has some usage constraints.  It:
  85 @itemize @bullet
  86 @item
  87 can be disabled with --no-dane.
  88 @end itemize
  89
  90 This option will, in addition to certificate authentication using
  91 the trusted CAs, verify the server certificates using on the DANE information
  92 available via DNSSEC.
  93 @anchor{gnutls-cli local-dns}
  94 @subheading local-dns option
  95
  96 This is the ``use the local dns server for dnssec resolving'' option.
  97
  98 @noindent
  99 This option has some usage constraints.  It:
 100 @itemize @bullet
 101 @item
 102 can be disabled with --no-local-dns.
 103 @end itemize
 104
 105 This option will use the local DNS server for DNSSEC.
 106 This is disabled by default due to many servers not allowing DNSSEC.
 107 @anchor{gnutls-cli ca-verification}
 108 @subheading ca-verification option
 109
 110 This is the ``disable ca certificate verification'' option.
 111
 112 @noindent
 113 This option has some usage constraints.  It:
 114 @itemize @bullet
 115 @item
 116 can be disabled with --no-ca-verification.
 117 @item
 118 It is enabled by default.
 119 @end itemize
 120
 121 This option will disable CA certificate verification. It is to be used with the --dane or --tofu options.
 122 @anchor{gnutls-cli ocsp}
 123 @subheading ocsp option
 124
 125 This is the ``enable ocsp certificate verification'' option.
 126
 127 @noindent
 128 This option has some usage constraints.  It:
 129 @itemize @bullet
 130 @item
 131 can be disabled with --no-ocsp.
 132 @end itemize
 133
 134 This option will enable verification of the peer's certificate using ocsp
 135 @anchor{gnutls-cli resume}
 136 @subheading resume option (-r)
 137
 138 This is the ``establish a session and resume'' option.
 139 Connect, establish a session, reconnect and resume.
 140 @anchor{gnutls-cli rehandshake}
 141 @subheading rehandshake option (-e)
 142
 143 This is the ``establish a session and rehandshake'' option.
 144 Connect, establish a session and rehandshake immediately.
 145 @anchor{gnutls-cli starttls}
 146 @subheading starttls option (-s)
 147
 148 This is the ``connect, establish a plain session and start tls'' option.
 149 The TLS session will be initiated when EOF or a SIGALRM is received.
 150 @anchor{gnutls-cli app-proto}
 151 @subheading app-proto option
 152
 153 This is an alias for the @code{starttls-proto} option,
 154 @pxref{gnutls-cli starttls-proto, the starttls-proto option documentation}.
 155
 156 @anchor{gnutls-cli starttls-proto}
 157 @subheading starttls-proto option
 158
 159 This is the ``the application protocol to be used to obtain the server's certificate (https, ftp, smtp, imap)'' option.
 160 This option takes a string argument.
 161
 162 @noindent
 163 This option has some usage constraints.  It:
 164 @itemize @bullet
 165 @item
 166 must not appear in combination with any of the following options:
 167 starttls.
 168 @end itemize
 169
 170 Specify the application layer protocol for STARTTLS. If the protocol is supported, gnutls-cli will proceed to the TLS negotiation.
 171 @anchor{gnutls-cli dh-bits}
 172 @subheading dh-bits option
 173
 174 This is the ``the minimum number of bits allowed for dh'' option.
 175 This option takes a number argument.
 176 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.
 177 @anchor{gnutls-cli priority}
 178 @subheading priority option
 179
 180 This is the ``priorities string'' option.
 181 This option takes a string argument.
 182 TLS algorithms and protocols to enable. You can
 183 use predefined sets of ciphersuites such as PERFORMANCE,
 184 NORMAL, PFS, SECURE128, SECURE256. The default is NORMAL.
 185
 186 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
 187 information on the allowed keywords
 188 @anchor{gnutls-cli ranges}
 189 @subheading ranges option
 190
 191 This is the ``use length-hiding padding to prevent traffic analysis'' option.
 192 When possible (e.g., when using CBC ciphersuites), use length-hiding padding to prevent traffic analysis.
 193 @anchor{gnutls-cli list}
 194 @subheading list option (-l)
 195
 196 This is the ``print a list of the supported algorithms and modes'' option.
 197
 198 @noindent
 199 This option has some usage constraints.  It:
 200 @itemize @bullet
 201 @item
 202 must not appear in combination with any of the following options:
 203 port.
 204 @end itemize
 205
 206 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
 207 @anchor{gnutls-cli alpn}
 208 @subheading alpn option
 209
 210 This is the ``application layer protocol'' option.
 211 This option takes a string argument.
 212
 213 @noindent
 214 This option has some usage constraints.  It:
 215 @itemize @bullet
 216 @item
 217 may appear an unlimited number of times.
 218 @end itemize
 219
 220 This option will set and enable the Application Layer Protocol Negotiation  (ALPN) in the TLS protocol.
 221 @anchor{gnutls-cli disable-extensions}
 222 @subheading disable-extensions option
 223
 224 This is the ``disable all the tls extensions'' option.
 225 This option disables all TLS extensions. Deprecated option. Use the priority string.
 226 @anchor{gnutls-cli inline-commands}
 227 @subheading inline-commands option
 228
 229 This is the ``inline commands of the form ^<cmd>^'' option.
 230 Enable inline commands of the form ^<cmd>^. The inline commands are expected to be in a line by themselves. The available commands are: resume and renegotiate.
 231 @anchor{gnutls-cli inline-commands-prefix}
 232 @subheading inline-commands-prefix option
 233
 234 This is the ``change the default delimiter for inline commands.'' option.
 235 This option takes a string argument.
 236 Change the default delimiter (^) used for inline commands. The delimiter is expected to be a single US-ASCII character (octets 0 - 127). This option is only relevant if inline commands are enabled via the inline-commands option
 237 @anchor{gnutls-cli provider}
 238 @subheading provider option
 239
 240 This is the ``specify the pkcs #11 provider library'' option.
 241 This option takes a file argument.
 242 This will override the default options in /etc/gnutls/pkcs11.conf
 243 @anchor{gnutls-cli exit status}
 244 @subheading gnutls-cli exit status
 245
 246 One of the following exit values will be returned:
 247 @table @samp
 248 @item 0 (EXIT_SUCCESS)
 249 Successful program execution.
 250 @item 1 (EXIT_FAILURE)
 251 The operation failed or the command syntax was not valid.
 252 @end table
 253 @anchor{gnutls-cli See Also}
 254 @subheading gnutls-cli See Also
 255 gnutls-cli-debug(1), gnutls-serv(1)
 256 @anchor{gnutls-cli Examples}
 257 @subheading gnutls-cli Examples
 258 @subheading Connecting using PSK authentication
 259 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.
 260 @example
 261 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
 262     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
 263     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
 264 Resolving 'localhost'...
 265 Connecting to '127.0.0.1:5556'...
 266 - PSK authentication.
 267 - Version: TLS1.1
 268 - Key Exchange: PSK
 269 - Cipher: AES-128-CBC
 270 - MAC: SHA1
 271 - Compression: NULL
 272 - Handshake was completed
 273
 274 - Simple Client Mode:
 275 @end example
 276 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.
 277
 278 @subheading Listing ciphersuites in a priority string
 279 To list the ciphersuites in a priority string:
 280 @example
 281 $ ./gnutls-cli --priority SECURE192 -l
 282 Cipher suites for SECURE192
 283 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
 284 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
 285 TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
 286 TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
 287 TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
 288 TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2
 289
 290 Certificate types: CTYPE-X.509
 291 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
 292 Compression: COMP-NULL
 293 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
 294 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
 295 @end example
 296
 297 @subheading Connecting using a PKCS #11 token
 298 To connect to a server using a certificate and a private key present in a PKCS #11 token you
 299 need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
 300
 301 Those can be found using "p11tool --list-tokens" and then listing all the objects in the
 302 needed token, and using the appropriate.
 303 @example
 304 $ p11tool --list-tokens
 305
 306 Token 0:
 307 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
 308 Label: Test
 309 Manufacturer: EnterSafe
 310 Model: PKCS15
 311 Serial: 1234
 312
 313 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
 314
 315 Object 0:
 316 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert
 317 Type: X.509 Certificate
 318 Label: client
 319 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
 320
 321 $ export MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert"
 322 $ export MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=private"
 323
 324 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile MYCERT
 325 @end example
 326 Notice that the private key only differs from the certificate in the object-type.