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  May 29, 2014 at 07:10:26 PM by AutoGen 5.18.2
  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 dh-bits}
 151 @subheading dh-bits option
 152
 153 This is the ``the minimum number of bits allowed for dh'' option.
 154 This option takes a number argument.
 155 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.
 156 @anchor{gnutls-cli priority}
 157 @subheading priority option
 158
 159 This is the ``priorities string'' option.
 160 This option takes a string argument.
 161 TLS algorithms and protocols to enable. You can
 162 use predefined sets of ciphersuites such as PERFORMANCE,
 163 NORMAL, PFS, SECURE128, SECURE256. The default is NORMAL.
 164
 165 Check  the  GnuTLS  manual  on  section  ``Priority strings'' for more
 166 information on the allowed keywords
 167 @anchor{gnutls-cli ranges}
 168 @subheading ranges option
 169
 170 This is the ``use length-hiding padding to prevent traffic analysis'' option.
 171 When possible (e.g., when using CBC ciphersuites), use length-hiding padding to prevent traffic analysis.
 172 @anchor{gnutls-cli list}
 173 @subheading list option (-l)
 174
 175 This is the ``print a list of the supported algorithms and modes'' option.
 176 Print a list of the supported algorithms and modes. If a priority string is given then only the enabled ciphersuites are shown.
 177 @anchor{gnutls-cli alpn}
 178 @subheading alpn option
 179
 180 This is the ``application layer protocol'' option.
 181 This option takes a string argument.
 182
 183 @noindent
 184 This option has some usage constraints.  It:
 185 @itemize @bullet
 186 @item
 187 may appear an unlimited number of times.
 188 @end itemize
 189
 190 This option will set and enable the Application Layer Protocol Negotiation  (ALPN) in the TLS protocol.
 191 @anchor{gnutls-cli disable-extensions}
 192 @subheading disable-extensions option
 193
 194 This is the ``disable all the tls extensions'' option.
 195 This option disables all TLS extensions. Deprecated option. Use the priority string.
 196 @anchor{gnutls-cli inline-commands}
 197 @subheading inline-commands option
 198
 199 This is the ``inline commands of the form ^<cmd>^'' option.
 200 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.
 201 @anchor{gnutls-cli inline-commands-prefix}
 202 @subheading inline-commands-prefix option
 203
 204 This is the ``change the default (^) used as a delimiter for inline commands.
 205                                 the value is a single us-ascii character (octets 0 - 127).'' option.
 206 This option takes a string argument.
 207 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
 208 @anchor{gnutls-cli provider}
 209 @subheading provider option
 210
 211 This is the ``specify the pkcs #11 provider library'' option.
 212 This option takes a file argument.
 213 This will override the default options in /etc/gnutls/pkcs11.conf
 214 @anchor{gnutls-cli exit status}
 215 @subheading gnutls-cli exit status
 216
 217 One of the following exit values will be returned:
 218 @table @samp
 219 @item 0 (EXIT_SUCCESS)
 220 Successful program execution.
 221 @item 1 (EXIT_FAILURE)
 222 The operation failed or the command syntax was not valid.
 223 @end table
 224 @anchor{gnutls-cli See Also}
 225 @subheading gnutls-cli See Also
 226 gnutls-cli-debug(1), gnutls-serv(1)
 227 @anchor{gnutls-cli Examples}
 228 @subheading gnutls-cli Examples
 229 @subheading Connecting using PSK authentication
 230 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.
 231 @example
 232 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
 233     --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
 234     --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
 235 Resolving 'localhost'...
 236 Connecting to '127.0.0.1:5556'...
 237 - PSK authentication.
 238 - Version: TLS1.1
 239 - Key Exchange: PSK
 240 - Cipher: AES-128-CBC
 241 - MAC: SHA1
 242 - Compression: NULL
 243 - Handshake was completed
 244
 245 - Simple Client Mode:
 246 @end example
 247 By keeping the --pskusername parameter and removing the --pskkey parameter, it will query only for the password during the handshake.
 248
 249 @subheading Listing ciphersuites in a priority string
 250 To list the ciphersuites in a priority string:
 251 @example
 252 $ ./gnutls-cli --priority SECURE192 -l
 253 Cipher suites for SECURE192
 254 TLS_ECDHE_ECDSA_AES_256_CBC_SHA384         0xc0, 0x24   TLS1.2
 255 TLS_ECDHE_ECDSA_AES_256_GCM_SHA384         0xc0, 0x2e   TLS1.2
 256 TLS_ECDHE_RSA_AES_256_GCM_SHA384           0xc0, 0x30   TLS1.2
 257 TLS_DHE_RSA_AES_256_CBC_SHA256             0x00, 0x6b   TLS1.2
 258 TLS_DHE_DSS_AES_256_CBC_SHA256             0x00, 0x6a   TLS1.2
 259 TLS_RSA_AES_256_CBC_SHA256                 0x00, 0x3d   TLS1.2
 260
 261 Certificate types: CTYPE-X.509
 262 Protocols: VERS-TLS1.2, VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0, VERS-DTLS1.0
 263 Compression: COMP-NULL
 264 Elliptic curves: CURVE-SECP384R1, CURVE-SECP521R1
 265 PK-signatures: SIGN-RSA-SHA384, SIGN-ECDSA-SHA384, SIGN-RSA-SHA512, SIGN-ECDSA-SHA512
 266 @end example
 267
 268 @subheading Connecting using a PKCS #11 token
 269 To connect to a server using a certificate and a private key present in a PKCS #11 token you
 270 need to substitute the PKCS 11 URLs in the x509certfile and x509keyfile parameters.
 271
 272 Those can be found using "p11tool --list-tokens" and then listing all the objects in the
 273 needed token, and using the appropriate.
 274 @example
 275 $ p11tool --list-tokens
 276
 277 Token 0:
 278 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test
 279 Label: Test
 280 Manufacturer: EnterSafe
 281 Model: PKCS15
 282 Serial: 1234
 283
 284 $ p11tool --login --list-certs "pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test"
 285
 286 Object 0:
 287 URL: pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert
 288 Type: X.509 Certificate
 289 Label: client
 290 ID: 2a:97:0d:58:d1:51:3c:23:07:ae:4e:0d:72:26:03:7d:99:06:02:6a
 291
 292 $ export MYCERT="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=cert"
 293 $ export MYKEY="pkcs11:model=PKCS15;manufacturer=MyMan;serial=1234;token=Test;object=client;object-type=private"
 294
 295 $ gnutls-cli www.example.com --x509keyfile $MYKEY --x509certfile MYCERT
 296 @end example
 297 Notice that the private key only differs from the certificate in the object-type.