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