Documentation updates

1 files changed, 46 insertions, 19 deletions

diff --git a/doc/manual/cli.rst b/doc/manual/cli.rst
index 592aeafbc..c88e1ee90 100644
--- a/doc/manual/cli.rst
+++ b/doc/manual/cli.rst
@@ -11,14 +11,18 @@ of functions of the Botan library in the shell.
 All commands follow the syntax ``botan <command> <command-options>``.
 
 If ``botan`` is run with an unknown command, or without any command, or with the
-``--help`` option, all available commands with their options will be printed.
+``--help`` option, all available commands will be printed. If a particular
+command is run with the ``--help`` option (like ``botan <command> --help``)
+some information about the usage of the command is printed.
 
 Hash Function
 ----------------
-``hash --algo=SHA-256 --buf-size=4096 files``
+``hash --algo=SHA-256 --buf-size=4096 --no-fsname files``
   Compute the *algo* digest over the data in any number of *files*. If
   no files are listed on the command line, the input source defaults
-  to standard input.
+  to standard input. Unless the ``--no-fsname`` option is given, the
+  filename is printed alongside the hash, in the style of tools such
+  as ``sha256sum``.
 
 Password Hash
 ----------------
@@ -32,10 +36,11 @@ Password Hash
 
 HMAC
 ----------------
-``hmac --hash=SHA-256 --buf-size=4096 key files``
+``hmac --hash=SHA-256 --buf-size=4096 --no-fsname key files``
   Compute the HMAC tag with the cryptographic hash function *hash*
   using the key in file *key* over the data in *files*. *files*
-  defaults to STDIN.
+  defaults to STDIN. Unless the ``--no-fsname`` option is given, the
+  filename is printed alongside the HMAC value.
 
 Public Key Cryptography
 -------------------------------------
@@ -53,13 +58,21 @@ Public Key Cryptography
     - For DSA *params* specifies the DSA parameters. It defaults to dsa/botan/2048.
     - For EC algorithms *params* specifies the elliptic curve. It defaults to secp256r1.
 
+  The default *pbe* algorithm is "PBE-PKCS5v20(AES-256/CBC,SHA-256)".
+
+  With PBE-PKCS5v20 you can select any CBC or GCM mode cipher which has an OID
+  defined (such as 3DES, Camellia, SM4, Twofish or Serpent). However most other
+  implementations support only AES or 3DES in CBC mode. You can also choose
+  Scrypt instead of PBKDF2, by using "Scrypt" instead of the name of a hash
+  function, for example "PBE-PKCS5v20(AES-256/CBC,Scrypt)"
+
 ``pkcs8 --pass-in= --pub-out --der-out --pass-out= --pbe= --pbe-millis=300 key``
   Open a PKCS #8 formatted key at *key*. If *key* is encrypted, the passphrase
   must be passed as *pass-in*. It is possible to (re)encrypt the read key with
   the passphrase passed as *pass-out*. The parameters *pbe-millis* and *pbe*
   work similarly to ``keygen``.
 
-``sign --passphrase= --hash=SHA-256 --emsa= key file``
+``sign --der-format --passphrase= --hash=SHA-256 --emsa= key file``
   Sign the data in *file* using the PKCS #8 private key *key*. If *key* is
   encrypted, the used passphrase must be passed as *pass-in*. *emsa* specifies
   the signature scheme and *hash* the cryptographic hash function used in the
@@ -68,13 +81,17 @@ Public Key Cryptography
     - For RSA signatures EMSA4 (RSA-PSS) is the default scheme.
     - For ECDSA and DSA *emsa* defaults to EMSA1 (signing the hash directly)
 
-``verify --hash=SHA-256 --emsa= pubkey file signature``
+  For ECDSA and DSA, the option ``--der-format`` outputs the signature as an
+  ASN.1 encoded blob. Some other tools (including ``openssl``) default to this
+  format.
+
+``verify --der-format --hash=SHA-256 --emsa= pubkey file signature``
   Verify the authenticity of the data in *file* with the provided signature
   *signature* and the public key *pubkey*. Similarly to the signing process,
   *emsa* specifies the signature scheme and *hash* the cryptographic hash
   function used in the scheme.
 
-``gen_dl_group --pbits=1024 --qbits=0 --type=subgroup``
+``gen_dl_group --pbits=1024 --qbits=0 --seed= --type=subgroup``
   Generate ANSI X9.42 encoded Diffie-Hellman group parameters.
 
     - If *type=subgroup* is passed, the size of the prime subgroup q is sampled
@@ -82,6 +99,10 @@ Public Key Cryptography
       passed, its length is estimated from *pbits* as described in RFC 3766.
     - If *type=strong* is passed, p is sampled as a safe prime with length
       *pbits* and the prime subgroup has size q with *pbits*-1 length.
+    - If *type=dsa* is used, p and q are generated by the algorithm specified in
+      FIPS 186-4. If the ``--seed`` parameter is used, it allows to select the
+      seed value, instead of one being randomly generated. If the seed does not
+      in fact generate a valid DSA group, the command will fail.
 
 ``dl_group_info --pem name``
   Print raw Diffie-Hellman parameters (p,g) of the standarized DH group
@@ -185,6 +206,7 @@ Number Theory
 
 ``factor n``
   Factor the integer *n* using a combination of trial division by small primes, and Pollard's Rho algorithm.
+  It can in reasonable time factor integers up to 150 bits or so.
 
 ``gen_prime --count=1 bits``
   Samples *count* primes with a length of *bits* bits.
@@ -192,7 +214,7 @@ Number Theory
 PSK Database
 --------------------
 
-Only available if sqlite3 support was compiled in.
+The PSK database commands are only available if sqlite3 support was compiled in.
 
 ``psk_set db db_key name psk``
   Using the PSK database named db and encrypting under the (hex) key ``db_key``,
@@ -230,12 +252,14 @@ Data Encoding/Decoding
 Miscellaneous Commands
 -------------------------------------
 ``version --full``
-  Print the version number. If option ``-full`` is provided additional details are printed.
+  Print the version number. If option ``--full`` is provided,
+  additional details are printed.
 
 ``config info_type``
   Prints build information, useful for applications which want to
   build against the library.  The ``info_type`` argument can be any of
-  ``prefix``, ``cflags``, ``ldflags``, or ``libs``.
+  ``prefix``, ``cflags``, ``ldflags``, or ``libs``. This is
+  similar to information provided by the ``pkg-config`` tool.
 
 ``cpuid``
   List available processor flags (aes_ni, SIMD extensions, ...).
@@ -244,18 +268,21 @@ Miscellaneous Commands
   Decode and print *file* with ASN.1 Basic Encoding Rules (BER).
 
 ``http_get url``
-  Retrieve ressource from the passed http/https *url*.
+  Retrieve ressource from the passed http *url*.
 
-``speed --msec=100 --provider= --buf-size=4096 algos``
-  Measures the speed of the passed *algos*. If no *algos* are passed
-  all available speed tests are executed. *msec* (in milliseconds)
-  sets the period of measurement for each algorithm.
+``speed --msec=500 --provider= --buf-size=1024 algos``
+  Measures the speed of the passed *algos*. If no *algos* are passed all
+  available speed tests are executed. *msec* (in milliseconds) sets the period
+  of measurement for each algorithm. The *buf-size* option allows testing the
+  same algorithm on one or more input sizes, for example
+  ``speed --buf-size=136,1500 AES-128/GCM`` tests the performance of GCM for
+  small and large packet sizes.
 
 ``rng --system --rdrand bytes``
   Sample *bytes* random bytes from the specified random number generator. If
-  *system* is set, the Botan System_RNG is used. If *system* is unset and
-  *rdrand* is set, the hardware rng RDRAND_RNG is used.  If both are unset, the
-  Botan AutoSeeded_RNG is used.
+  *system* is set, the system RNG is used. If *system* is unset and *rdrand* is
+  set, the hardware RDRAND instruction is used if available. If both are unset,
+  HMAC_DRBG is used.
 
 ``cc_encrypt CC passphrase --tweak=``
   Encrypt the passed valid credit card number *CC* using FPE encryption and the