doc/cha-programs.texi

   1 @node Included programs
   2 @chapter Included Programs
   3
   4 Included with @acronym{GnuTLS} are also a few command line tools that
   5 let you use the library for common tasks without writing an
   6 application.  The applications are discussed in this chapter.
   7
   8 @menu
   9 * Invoking certtool::
  10 * Invoking gnutls-cli::
  11 * Invoking gnutls-cli-debug::
  12 * Invoking gnutls-serv::
  13 * Invoking psktool::
  14 * Invoking srptool::
  15 * Invoking p11tool::
  16 @end menu
  17
  18 @node Invoking certtool
  19 @section Invoking certtool
  20 @cindex certtool
  21
  22 This is a program to generate @acronym{X.509} certificates, certificate
  23 requests, CRLs and private keys.
  24
  25 @verbatim
  26 Certtool help
  27 Usage: certtool [options]
  28      -s, --generate-self-signed
  29                               Generate a self-signed certificate.
  30      -c, --generate-certificate
  31                               Generate a signed certificate.
  32      --generate-proxy         Generate a proxy certificate.
  33      --generate-crl           Generate a CRL.
  34      -u, --update-certificate
  35                               Update a signed certificate.
  36      -p, --generate-privkey   Generate a private key.
  37      -q, --generate-request   Generate a PKCS #10 certificate
  38                               request.
  39      -e, --verify-chain       Verify a PEM encoded certificate chain.
  40                               The last certificate in the chain must
  41                               be a self signed one.
  42      --verify-crl             Verify a CRL.
  43      --generate-dh-params     Generate PKCS #3 encoded Diffie-Hellman
  44                               parameters.
  45      --get-dh-params          Get the included PKCS #3 encoded Diffie
  46                               Hellman parameters.
  47      --load-privkey FILE      Private key file to use.
  48      --load-request FILE      Certificate request file to use.
  49      --load-certificate FILE
  50                               Certificate file to use.
  51      --load-ca-privkey FILE   Certificate authority's private key
  52                               file to use.
  53      --load-ca-certificate FILE
  54                               Certificate authority's certificate
  55                               file to use.
  56      --password PASSWORD      Password to use.
  57      -i, --certificate-info   Print information on a certificate.
  58      -l, --crl-info           Print information on a CRL.
  59      --p12-info               Print information on a PKCS #12
  60                               structure.
  61      --p7-info                Print information on a PKCS #7
  62                               structure.
  63      --smime-to-p7            Convert S/MIME to PKCS #7 structure.
  64      -k, --key-info           Print information on a private key.
  65      --fix-key                Regenerate the parameters in a private
  66                               key.
  67      --to-p12                 Generate a PKCS #12 structure.
  68      -8, --pkcs8              Use PKCS #8 format for private keys.
  69      --dsa                    Use DSA keys.
  70      --hash STR               Hash algorithm to use for signing
  71                               (MD5,SHA1,RMD160).
  72      --export-ciphers         Use weak encryption algorithms.
  73      --inder                  Use DER format for input certificates
  74                               and private keys.
  75      --outder                 Use DER format for output certificates
  76                               and private keys.
  77      --bits BITS              specify the number of bits for key
  78                               generation.
  79      --outfile FILE           Output file.
  80      --infile FILE            Input file.
  81      --template FILE          Template file to use for non
  82                               interactive operation.
  83      -d, --debug LEVEL        specify the debug level. Default is 1.
  84      -h, --help               shows this help text
  85      -v, --version            shows the program's version
  86 @end verbatim
  87
  88 The program can be used interactively or non interactively by
  89 specifying the @code{--template} command line option. See below for an
  90 example of a template file.
  91
  92 How to use certtool interactively:
  93
  94 @itemize
  95 @item
  96 To generate parameters for Diffie-Hellman key exchange, use the command:
  97 @example
  98 $ certtool --generate-dh-params --outfile dh.pem
  99 @end example
 100
 101 @item
 102 To generate parameters for the RSA-EXPORT key exchange, use the command:
 103 @example
 104 $ certtool --generate-privkey --bits 512 --outfile rsa.pem
 105 @end example
 106
 107 @end itemize
 108
 109 @itemize
 110
 111 @item
 112 To create a self signed certificate, use the command:
 113 @example
 114 $ certtool --generate-privkey --outfile ca-key.pem
 115 $ certtool --generate-self-signed --load-privkey ca-key.pem \
 116    --outfile ca-cert.pem
 117 @end example
 118
 119 Note that a self-signed certificate usually belongs to a certificate
 120 authority, that signs other certificates.
 121
 122 @item
 123 To create a private key (RSA by default), run:
 124
 125 @example
 126 $ certtool --generate-privkey --outfile key.pem
 127 @end example
 128
 129 To create a DSA private key, run:
 130
 131 @example
 132 $ certtool --dsa --generate-privkey --outfile key-dsa.pem
 133 @end example
 134
 135 @item
 136 To generate a certificate using the private key, use the command:
 137
 138 @example
 139 $ certtool --generate-certificate --load-privkey key.pem \
 140    --outfile cert.pem --load-ca-certificate ca-cert.pem \
 141    --load-ca-privkey ca-key.pem
 142 @end example
 143
 144 @item
 145 To create a certificate request (needed when the certificate is issued by
 146 another party), run:
 147
 148 @example
 149 $ certtool --generate-request --load-privkey key.pem \
 150   --outfile request.pem
 151 @end example
 152
 153 @item
 154 To generate a certificate using the previous request, use the command:
 155
 156 @example
 157 $ certtool --generate-certificate --load-request request.pem \
 158    --outfile cert.pem \
 159    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
 160 @end example
 161
 162 @item
 163 To view the certificate information, use:
 164
 165 @example
 166 $ certtool --certificate-info --infile cert.pem
 167 @end example
 168
 169 @item
 170 To generate a @acronym{PKCS} #12 structure using the previous key and
 171 certificate, use the command:
 172
 173 @example
 174 $ certtool --load-certificate cert.pem --load-privkey key.pem \
 175   --to-p12 --outder --outfile key.p12
 176 @end example
 177
 178 Some tools (reportedly web browsers) have problems with that file
 179 because it does not contain the CA certificate for the certificate.
 180 To work around that problem in the tool, you can use the
 181 @samp{--load-ca-certificate} parameter as follows:
 182
 183 @example
 184 $ certtool --load-ca-certificate ca.pem \
 185   --load-certificate cert.pem --load-privkey key.pem \
 186   --to-p12 --outder --outfile key.p12
 187 @end example
 188
 189 @item
 190 Proxy certificate can be used to delegate your credential to a
 191 temporary, typically short-lived, certificate.  To create one from the
 192 previously created certificate, first create a temporary key and then
 193 generate a proxy certificate for it, using the commands:
 194
 195 @example
 196 $ certtool --generate-privkey > proxy-key.pem
 197 $ certtool --generate-proxy --load-ca-privkey key.pem \
 198   --load-privkey proxy-key.pem --load-certificate cert.pem \
 199   --outfile proxy-cert.pem
 200 @end example
 201
 202 @item
 203 To create an empty Certificate Revocation List (CRL) do:
 204
 205 @example
 206 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem
 207 @end example
 208
 209 To create a CRL that contains some revoked certificates, place the
 210 certificates in a file and use @code{--load-certificate} as follows:
 211
 212 @example
 213 $ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
 214 @end example
 215
 216 @item
 217 To verify a Certificate Revocation List (CRL) do:
 218
 219 @example
 220 $ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
 221 @end example
 222
 223 @end itemize
 224
 225 Certtool's template file format:
 226
 227 @itemize
 228
 229 @item
 230 Firstly create a file named 'cert.cfg' that contains the information
 231 about the certificate. An example file is listed below.
 232
 233 @item
 234 Then execute:
 235
 236 @example
 237 $ certtool --generate-certificate cert.pem --load-privkey key.pem  \
 238    --template cert.cfg \
 239    --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
 240 @end example
 241
 242 @end itemize
 243
 244 An example certtool template file:
 245
 246 @example
 247 # X.509 Certificate options
 248 #
 249 # DN options
 250
 251 # The organization of the subject.
 252 organization = "Koko inc."
 253
 254 # The organizational unit of the subject.
 255 unit = "sleeping dept."
 256
 257 # The locality of the subject.
 258 # locality =
 259
 260 # The state of the certificate owner.
 261 state = "Attiki"
 262
 263 # The country of the subject. Two letter code.
 264 country = GR
 265
 266 # The common name of the certificate owner.
 267 cn = "Cindy Lauper"
 268
 269 # A user id of the certificate owner.
 270 #uid = "clauper"
 271
 272 # If the supported DN OIDs are not adequate you can set
 273 # any OID here.
 274 # For example set the X.520 Title and the X.520 Pseudonym
 275 # by using OID and string pairs.
 276 #dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal"
 277
 278 # This is deprecated and should not be used in new
 279 # certificates.
 280 # pkcs9_email = "none@@none.org"
 281
 282 # The serial number of the certificate
 283 serial = 007
 284
 285 # In how many days, counting from today, this certificate will expire.
 286 expiration_days = 700
 287
 288 # X.509 v3 extensions
 289
 290 # A dnsname in case of a WWW server.
 291 #dns_name = "www.none.org"
 292 #dns_name = "www.morethanone.org"
 293
 294 # An IP address in case of a server.
 295 #ip_address = "192.168.1.1"
 296
 297 # An email in case of a person
 298 email = "none@@none.org"
 299
 300 # An URL that has CRLs (certificate revocation lists)
 301 # available. Needed in CA certificates.
 302 #crl_dist_points = "http://www.getcrl.crl/getcrl/"
 303
 304 # Whether this is a CA certificate or not
 305 #ca
 306
 307 # Whether this certificate will be used for a TLS client
 308 #tls_www_client
 309
 310 # Whether this certificate will be used for a TLS server
 311 #tls_www_server
 312
 313 # Whether this certificate will be used to sign data (needed
 314 # in TLS DHE ciphersuites).
 315 signing_key
 316
 317 # Whether this certificate will be used to encrypt data (needed
 318 # in TLS RSA ciphersuites). Note that it is preferred to use different
 319 # keys for encryption and signing.
 320 #encryption_key
 321
 322 # Whether this key will be used to sign other certificates.
 323 #cert_signing_key
 324
 325 # Whether this key will be used to sign CRLs.
 326 #crl_signing_key
 327
 328 # Whether this key will be used to sign code.
 329 #code_signing_key
 330
 331 # Whether this key will be used to sign OCSP data.
 332 #ocsp_signing_key
 333
 334 # Whether this key will be used for time stamping.
 335 #time_stamping_key
 336
 337 # Whether this key will be used for IPsec IKE operations.
 338 #ipsec_ike_key
 339 @end example
 340
 341 @node Invoking gnutls-cli
 342 @section Invoking gnutls-cli
 343 @cindex gnutls-cli
 344
 345 Simple client program to set up a TLS connection to some other
 346 computer.  It sets up a TLS connection and forwards data from the
 347 standard input to the secured socket and vice versa.
 348
 349 @verbatim
 350 GnuTLS test client
 351 Usage:  gnutls-cli [options] hostname
 352
 353      -d, --debug integer      Enable debugging
 354      -r, --resume             Connect, establish a session. Connect
 355                               again and resume this session.
 356      -s, --starttls           Connect, establish a plain session and
 357                               start TLS when EOF or a SIGALRM is
 358                               received.
 359      --crlf                   Send CR LF instead of LF.
 360      --x509fmtder             Use DER format for certificates to read
 361                               from.
 362      -f, --fingerprint        Send the openpgp fingerprint, instead
 363                               of the key.
 364      --disable-extensions     Disable all the TLS extensions.
 365      --print-cert             Print the certificate in PEM format.
 366      --recordsize integer     The maximum record size to advertize.
 367      -V, --verbose            More verbose output.
 368      --ciphers cipher1 cipher2...
 369                               Ciphers to enable.
 370      --protocols protocol1 protocol2...
 371                               Protocols to enable.
 372      --comp comp1 comp2...    Compression methods to enable.
 373      --macs mac1 mac2...      MACs to enable.
 374      --kx kx1 kx2...          Key exchange methods to enable.
 375      --ctypes certType1 certType2...
 376                               Certificate types to enable.
 377      --priority PRIORITY STRING
 378                               Priorities string.
 379      --x509cafile FILE        Certificate file to use.
 380      --x509crlfile FILE       CRL file to use.
 381      --pgpkeyfile FILE        PGP Key file to use.
 382      --pgpkeyring FILE        PGP Key ring file to use.
 383      --pgpcertfile FILE       PGP Public Key (certificate) file to
 384                               use.
 385      --pgpsubkey HEX|auto     PGP subkey to use.
 386      --x509keyfile FILE       X.509 key file to use.
 387      --x509certfile FILE      X.509 Certificate file to use.
 388      --srpusername NAME       SRP username to use.
 389      --srppasswd PASSWD       SRP password to use.
 390      --pskusername NAME       PSK username to use.
 391      --pskkey KEY             PSK key (in hex) to use.
 392      --opaque-prf-input DATA
 393                               Use Opaque PRF Input DATA.
 394      -p, --port PORT          The port to connect to.
 395      --insecure               Don't abort program if server
 396                               certificate can't be validated.
 397      -l, --list               Print a list of the supported
 398                               algorithms and modes.
 399      -h, --help               prints this help
 400      -v, --version            prints the program's version number
 401 @end verbatim
 402
 403 To connect to a server using PSK authentication, you may use something
 404 like:
 405
 406 @smallexample
 407 $ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+DHE-PSK:+PSK:-RSA:-DHE-RSA -d 4711
 408 @end smallexample
 409
 410 @menu
 411 * Example client PSK connection::
 412 @end menu
 413
 414 @node Example client PSK connection
 415 @subsection Example client PSK connection
 416 @cindex PSK client
 417
 418 If your server only supports the PSK ciphersuite, connecting to it
 419 should be as simple as connecting to the server:
 420
 421 @smallexample
 422 $ ./gnutls-cli -p 5556 localhost
 423 Resolving 'localhost'...
 424 Connecting to '127.0.0.1:5556'...
 425 - PSK client callback.
 426 Enter PSK identity: psk_identity
 427 Enter password:
 428 - PSK authentication.
 429 - Version: TLS1.1
 430 - Key Exchange: PSK
 431 - Cipher: AES-128-CBC
 432 - MAC: SHA1
 433 - Compression: NULL
 434 - Handshake was completed
 435
 436 - Simple Client Mode:
 437 @end smallexample
 438
 439 If the server supports several cipher suites, you may need to force it
 440 to chose PSK by using a cipher priority parameter such as
 441 @code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}.
 442
 443 @cindex Netconf
 444 Instead of using the Netconf-way to derive the PSK key from a
 445 password, you can also give the PSK username and key directly on the
 446 command line:
 447
 448 @smallexample
 449 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344  --priority NORMAL:+DHE-PSK:+PSK
 450 Resolving 'localhost'...
 451 Connecting to '127.0.0.1:5556'...
 452 - PSK authentication.
 453 - Version: TLS1.1
 454 - Key Exchange: PSK
 455 - Cipher: AES-128-CBC
 456 - MAC: SHA1
 457 - Compression: NULL
 458 - Handshake was completed
 459
 460 - Simple Client Mode:
 461 @end smallexample
 462
 463 By keeping the @code{--pskusername} parameter and removing the
 464 @code{--pskkey} parameter, it will query only for the password during
 465 the handshake.
 466
 467 @node Invoking gnutls-cli-debug
 468 @section Invoking gnutls-cli-debug
 469 @cindex gnutls-cli-debug
 470
 471 This program was created to assist in debugging @acronym{GnuTLS}, but
 472 it might be useful to extract a @acronym{TLS} server's capabilities.
 473 It's purpose is to connect onto a @acronym{TLS} server, perform some
 474 tests and print the server's capabilities. If called with the `-v'
 475 parameter a more checks will be performed. An example output is:
 476
 477 @smallexample
 478 crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556
 479 Resolving 'localhost'...
 480 Connecting to '127.0.0.1:5556'...
 481 Checking for TLS 1.1 support... yes
 482 Checking fallback from TLS 1.1 to... N/A
 483 Checking for TLS 1.0 support... yes
 484 Checking for SSL 3.0 support... yes
 485 Checking for version rollback bug in RSA PMS... no
 486 Checking for version rollback bug in Client Hello... no
 487 Checking whether we need to disable TLS 1.0... N/A
 488 Checking whether the server ignores the RSA PMS version... no
 489 Checking whether the server can accept Hello Extensions... yes
 490 Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes
 491 Checking whether the server can accept a bogus TLS record version in the client hello... yes
 492 Checking for certificate information... N/A
 493 Checking for trusted CAs... N/A
 494 Checking whether the server understands TLS closure alerts... yes
 495 Checking whether the server supports session resumption... yes
 496 Checking for export-grade ciphersuite support... no
 497 Checking RSA-export ciphersuite info... N/A
 498 Checking for anonymous authentication support... no
 499 Checking anonymous Diffie-Hellman group info... N/A
 500 Checking for ephemeral Diffie-Hellman support... no
 501 Checking ephemeral Diffie-Hellman group info... N/A
 502 Checking for AES cipher support (TLS extension)... yes
 503 Checking for 3DES cipher support... yes
 504 Checking for ARCFOUR 128 cipher support... yes
 505 Checking for ARCFOUR 40 cipher support... no
 506 Checking for MD5 MAC support... yes
 507 Checking for SHA1 MAC support... yes
 508 Checking for ZLIB compression support (TLS extension)... yes
 509 Checking for LZO compression support (GnuTLS extension)... yes
 510 Checking for max record size (TLS extension)... yes
 511 Checking for SRP authentication support (TLS extension)... yes
 512 Checking for OpenPGP authentication support (TLS extension)... no
 513 @end smallexample
 514
 515 @node Invoking gnutls-serv
 516 @section Invoking gnutls-serv
 517 @cindex gnutls-serv
 518
 519 Simple server program that listens to incoming TLS connections.
 520
 521 @verbatim
 522 GnuTLS test server
 523 Usage: gnutls-serv [options]
 524
 525      -d, --debug integer      Enable debugging
 526      -g, --generate           Generate Diffie-Hellman Parameters.
 527      -p, --port integer       The port to connect to.
 528      -q, --quiet              Suppress some messages.
 529      --nodb                   Does not use the resume database.
 530      --http                   Act as an HTTP Server.
 531      --echo                   Act as an Echo Server.
 532      --dhparams FILE          DH params file to use.
 533      --x509fmtder             Use DER format for certificates
 534      --x509cafile FILE        Certificate file to use.
 535      --x509crlfile FILE       CRL file to use.
 536      --pgpkeyring FILE        PGP Key ring file to use.
 537      --pgpkeyfile FILE        PGP Key file to use.
 538      --pgpcertfile FILE       PGP Public Key (certificate) file to
 539                               use.
 540      --pgpsubkey HEX|auto     PGP subkey to use.
 541      --x509keyfile FILE       X.509 key file to use.
 542      --x509certfile FILE      X.509 Certificate file to use.
 543      --x509dsakeyfile FILE    Alternative X.509 key file to use.
 544      --x509dsacertfile FILE   Alternative X.509 certificate file to
 545                               use.
 546      -r, --require-cert       Require a valid certificate.
 547      -a, --disable-client-cert
 548                               Disable request for a client
 549                               certificate.
 550      --pskpasswd FILE         PSK password file to use.
 551      --pskhint HINT           PSK identity hint to use.
 552      --srppasswd FILE         SRP password file to use.
 553      --srppasswdconf FILE     SRP password conf file to use.
 554      --opaque-prf-input DATA
 555                               Use Opaque PRF Input DATA.
 556      --ciphers cipher1 cipher2...
 557                               Ciphers to enable.
 558      --protocols protocol1 protocol2...
 559                               Protocols to enable.
 560      --comp comp1 comp2...    Compression methods to enable.
 561      --macs mac1 mac2...      MACs to enable.
 562      --kx kx1 kx2...          Key exchange methods to enable.
 563      --ctypes certType1 certType2...
 564                               Certificate types to enable.
 565      --priority PRIORITY STRING
 566                               Priorities string.
 567      -l, --list               Print a list of the supported
 568                               algorithms  and modes.
 569      -h, --help               prints this help
 570      -v, --version            prints the program's version number
 571 @end verbatim
 572
 573 @subsection Setting Up a Test HTTPS Server
 574 @cindex HTTPS server
 575 @cindex debug server
 576
 577 Running your own TLS server based on GnuTLS can be useful when
 578 debugging clients and/or GnuTLS itself.  This section describes how to
 579 use @code{gnutls-serv} as a simple HTTPS server.
 580
 581 The most basic server can be started as:
 582
 583 @example
 584 gnutls-serv --http
 585 @end example
 586
 587 It will only support anonymous ciphersuites, which many TLS clients
 588 refuse to use.
 589
 590 The next step is to add support for X.509.  First we generate a CA:
 591
 592 @example
 593 certtool --generate-privkey > x509-ca-key.pem
 594 echo 'cn = GnuTLS test CA' > ca.tmpl
 595 echo 'ca' >> ca.tmpl
 596 echo 'cert_signing_key' >> ca.tmpl
 597 certtool --generate-self-signed --load-privkey x509-ca-key.pem \
 598   --template ca.tmpl --outfile x509-ca.pem
 599 ...
 600 @end example
 601
 602 Then generate a server certificate.  Remember to change the dns_name
 603 value to the name of your server host, or skip that command to avoid
 604 the field.
 605
 606 @example
 607 certtool --generate-privkey > x509-server-key.pem
 608 echo 'organization = GnuTLS test server' > server.tmpl
 609 echo 'cn = test.gnutls.org' >> server.tmpl
 610 echo 'tls_www_server' >> server.tmpl
 611 echo 'encryption_key' >> server.tmpl
 612 echo 'signing_key' >> server.tmpl
 613 echo 'dns_name = test.gnutls.org' >> server.tmpl
 614 certtool --generate-certificate --load-privkey x509-server-key.pem \
 615   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 616   --template server.tmpl --outfile x509-server.pem
 617 ...
 618 @end example
 619
 620 For use in the client, you may want to generate a client certificate
 621 as well.
 622
 623 @example
 624 certtool --generate-privkey > x509-client-key.pem
 625 echo 'cn = GnuTLS test client' > client.tmpl
 626 echo 'tls_www_client' >> client.tmpl
 627 echo 'encryption_key' >> client.tmpl
 628 echo 'signing_key' >> client.tmpl
 629 certtool --generate-certificate --load-privkey x509-client-key.pem \
 630   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 631   --template client.tmpl --outfile x509-client.pem
 632 ...
 633 @end example
 634
 635 To be able to import the client key/certificate into some
 636 applications, you will need to convert them into a PKCS#12 structure.
 637 This also encrypts the security sensitive key with a password.
 638
 639 @example
 640 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
 641 @end example
 642
 643 For icing, we'll create a proxy certificate for the client too.
 644
 645 @example
 646 certtool --generate-privkey > x509-proxy-key.pem
 647 echo 'cn = GnuTLS test client proxy' > proxy.tmpl
 648 certtool --generate-proxy --load-privkey x509-proxy-key.pem \
 649   --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \
 650   --load-certificate x509-client.pem --template proxy.tmpl \
 651   --outfile x509-proxy.pem
 652 ...
 653 @end example
 654
 655 Then start the server again:
 656
 657 @example
 658 gnutls-serv --http \
 659             --x509cafile x509-ca.pem \
 660             --x509keyfile x509-server-key.pem \
 661             --x509certfile x509-server.pem
 662 @end example
 663
 664 Try connecting to the server using your web browser.  Note that the
 665 server listens to port 5556 by default.
 666
 667 While you are at it, to allow connections using DSA, you can also
 668 create a DSA key and certificate for the server.  These credentials
 669 will be used in the final example below.
 670
 671 @example
 672 certtool --generate-privkey --dsa > x509-server-key-dsa.pem
 673 certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \
 674   --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \
 675   --template server.tmpl --outfile x509-server-dsa.pem
 676 ...
 677 @end example
 678
 679 The next step is to create OpenPGP credentials for the server.
 680
 681 @example
 682 gpg --gen-key
 683 ...enter whatever details you want, use 'test.gnutls.org' as name...
 684 @end example
 685
 686 Make a note of the OpenPGP key identifier of the newly generated key,
 687 here it was @code{5D1D14D8}.  You will need to export the key for
 688 GnuTLS to be able to use it.
 689
 690 @example
 691 gpg -a --export 5D1D14D8 > openpgp-server.txt
 692 gpg --export 5D1D14D8 > openpgp-server.bin
 693 gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin
 694 gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
 695 @end example
 696
 697 Let's start the server with support for OpenPGP credentials:
 698
 699 @example
 700 gnutls-serv --http \
 701             --pgpkeyfile openpgp-server-key.txt \
 702             --pgpcertfile openpgp-server.txt
 703 @end example
 704
 705 The next step is to add support for SRP authentication.
 706
 707 @example
 708 srptool --create-conf srp-tpasswd.conf
 709 srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt
 710 Enter password: [TYPE "foo"]
 711 @end example
 712
 713 Start the server with SRP support:
 714
 715 @example
 716 gnutls-serv --http \
 717             --srppasswdconf srp-tpasswd.conf \
 718             --srppasswd srp-passwd.txt
 719 @end example
 720
 721 Let's also add support for PSK.
 722
 723 @example
 724 $ psktool --passwd psk-passwd.txt
 725 @end example
 726
 727 Start the server with PSK support:
 728
 729 @example
 730 gnutls-serv --http \
 731             --pskpasswd psk-passwd.txt
 732 @end example
 733
 734 Finally, we start the server with all the earlier parameters and you
 735 get this command:
 736
 737 @example
 738 gnutls-serv --http \
 739             --x509cafile x509-ca.pem \
 740             --x509keyfile x509-server-key.pem \
 741             --x509certfile x509-server.pem \
 742             --x509dsakeyfile x509-server-key-dsa.pem \
 743             --x509dsacertfile x509-server-dsa.pem \
 744             --pgpkeyfile openpgp-server-key.txt \
 745             --pgpcertfile openpgp-server.txt \
 746             --srppasswdconf srp-tpasswd.conf \
 747             --srppasswd srp-passwd.txt \
 748             --pskpasswd psk-passwd.txt
 749 @end example
 750
 751 @menu
 752 * Example server PSK connection::
 753 @end menu
 754
 755 @node Example server PSK connection
 756 @subsection Example server PSK connection
 757 @cindex PSK server
 758
 759 To set up a PSK server with @code{gnutls-serv} you need to create PSK
 760 password file (@pxref{Invoking psktool}).  In the example below, I
 761 type @code{password} at the prompt.
 762
 763 @smallexample
 764 $ ./psktool -u psk_identity -p psks.txt
 765 Enter password:
 766 Key stored to psks.txt
 767 $ cat psks.txt
 768 psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
 769 $
 770 @end smallexample
 771
 772 After this, start the server pointing to the password file.  We
 773 disable DHE-PSK.
 774
 775 @smallexample
 776 $ ./gnutls-serv --pskpasswd psks.txt  --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK
 777 Set static Diffie-Hellman parameters, consider --dhparams.
 778 Echo Server ready. Listening to port '5556'.
 779 @end smallexample
 780
 781 You can now connect to the server using a PSK client (@pxref{Example
 782 client PSK connection}).
 783
 784 @node Invoking psktool
 785 @section Invoking psktool
 786 @cindex psktool
 787
 788 This is a program to manage @acronym{PSK} username and keys.
 789
 790 @verbatim
 791 PSKtool help
 792 Usage : psktool [options]
 793      -u, --username username
 794                               specify username.
 795      -p, --passwd FILE        specify a password file.
 796      -n, --netconf-hint HINT
 797                               derive key from Netconf password, using
 798                               HINT as the psk_identity_hint.
 799      -s, --keysize SIZE       specify the key size in bytes.
 800      -v, --version            prints the program's version number
 801      -h, --help               shows this help text
 802 @end verbatim
 803
 804 Normally the file will generate random keys for the indicate username.
 805 You may also derive PSK keys from passwords, using the algorithm
 806 specified in @file{draft-ietf-netconf-tls-02.txt}.  The algorithm
 807 needs a PSK identity hint, which you specify using
 808 @code{--netconf-hint}.  To derive a PSK key from a password with an
 809 empty PSK identity hint, using @code{--netconf-hint ""}.
 810
 811 @node Invoking srptool
 812 @section Invoking srptool
 813 @anchor{srptool}
 814 @cindex srptool
 815
 816 The @file{srptool} is a very simple program that emulates the programs
 817 in the @emph{Stanford SRP libraries}, see
 818 @url{http://srp.stanford.edu/}.  It is intended for use in places
 819 where you don't expect @acronym{SRP} authentication to be the used for
 820 system users.
 821
 822 Traditionally @emph{libsrp} used two files. One called @code{tpasswd}
 823 which holds usernames and verifiers, and @code{tpasswd.conf} which
 824 holds generators and primes.
 825
 826 How to use srptool:
 827
 828 @itemize
 829
 830 @item
 831 To create tpasswd.conf which holds the g and n values for
 832 @acronym{SRP} protocol (generator and a large prime), run:
 833
 834 @example
 835 $ srptool --create-conf /etc/tpasswd.conf
 836 @end example
 837
 838 @item
 839 This command will create /etc/tpasswd and will add user 'test' (you
 840 will also be prompted for a password).  Verifiers are stored by
 841 default in the way libsrp expects.
 842
 843 @example
 844 $ srptool --passwd /etc/tpasswd \
 845     --passwd-conf /etc/tpasswd.conf -u test
 846 @end example
 847
 848 @item
 849 This command will check against a password.  If the password matches
 850 the one in /etc/tpasswd you will get an ok.
 851
 852 @example
 853 $ srptool --passwd /etc/tpasswd \
 854     --passwd-conf /etc/tpasswd.conf --verify -u test
 855 @end example
 856
 857 @end itemize
 858
 859 @node Invoking p11tool
 860 @section Invoking p11tool
 861 @anchor{p11tool}
 862 @cindex p11tool
 863
 864 The @file{p11tool} is a program that helps with accessing tokens
 865 and security modules that support the PKCS #11 API. It requires
 866 the individual PKCS #11 modules to be loaded either with the
 867 @code{--provider} option, or by setting up the GnuTLS configuration
 868 file for PKCS #11 as in @ref{sec:pkcs11}.
 869
 870 @verbatim
 871 p11tool help
 872 Usage: p11tool [options]
 873
 874      --export URL             Export an object specified by a pkcs11
 875                               URL
 876      --list-tokens            List all available tokens
 877      --list-mechanisms URL    List all available mechanisms in token.
 878      --list-all               List all objects specified by a PKCS#11
 879                               URL
 880      --list-all-certs         List all certificates specified by a
 881                               PKCS#11 URL
 882      --list-certs             List certificates that have a private
 883                               key specified by a PKCS#11 URL
 884      --list-privkeys          List private keys specified by a
 885                               PKCS#11 URL
 886      --list-trusted           List certificates marked as trusted,
 887                               specified by a PKCS#11 URL
 888      --initialize URL         Initializes a PKCS11 token.
 889      --write URL              Writes loaded certificates, private or
 890                               secret keys to a PKCS11 token.
 891      --delete URL             Deletes objects matching the URL.
 892      --label label            Sets a label for the write operation.
 893      --trusted                Marks the certificate to be imported as
 894                               trusted.
 895      --login                  Force login to token
 896      --detailed-url           Export detailed URLs.
 897      --no-detailed-url        Export less detailed URLs.
 898      --secret-key HEX_KEY     Provide a hex encoded secret key.
 899      --load-privkey FILE      Private key file to use.
 900      --load-pubkey FILE       Private key file to use.
 901      --load-certificate FILE
 902                               Certificate file to use.
 903      -8, --pkcs8              Use PKCS #8 format for private keys.
 904      --inder                  Use DER format for input certificates
 905                               and private keys.
 906      --inraw                  Use RAW/DER format for input
 907                               certificates and private keys.
 908      --provider Library       Specify the pkcs11 provider library
 909      --outfile FILE           Output file.
 910      -d, --debug LEVEL        specify the debug level. Default is 1.
 911      -h, --help               shows this help text
 912 @end verbatim
 913
 914 After being provided the available PKCS #11 modules, it can list all tokens
 915 available in your system, the objects on the tokens, and perform operations
 916 on them.
 917
 918 Some examples on how to use p11tool:
 919
 920 @itemize
 921
 922 @item List all tokens
 923 @example
 924 $ p11tool --list-tokens
 925 @end example
 926
 927 @item List all objects
 928 @example
 929 $ p11tool --login --list-all
 930 @end example
 931
 932 @item To export an object
 933 @example
 934 $ p11tool --login --export pkcs11:(OBJECT URL)
 935 @end example
 936
 937 @item To copy an object to a token
 938 @example
 939 $ p11tool --login --write pkcs11:(TOKEN URL) --load-certificate (certificate file) --label "my_cert"
 940 @end example
 941
 942 @end itemize
 943
 944 Note that typically PKCS #11 private key objects are not allowed
 945 to be extracted from the token.